모든 악기 파트가 표현된 악보를 총보라고 하는데,
지휘전에 꼼꼼히 악보를 검토하고 코멘트를 달지.
그 코멘트는 악보에 대한 설명이 아님. to do 지.
지휘 연습하면서 자기가 해석한걸 빠뜨리지 않기 위해 사용하는 것임
자기만의 색깔을 내기 위한 자신의 코드지.
* * *
작곡가들이 악보에 몇가지 정의된 형식에 따라 부드럽게 아주 빠르게 노래하듯이 라고 적는건
논리가 아니라 감정의 영역을 다루기 때문이고, 사실은 템플릿이지.
지휘자와 연주자들이 적당히 자기 감정을 실을 수 있게 하는 것.
( 예외적으로 '팔꿈치로 치세요' 같은거 있지. all of me 같은 곡 )
* * *
악보는 코드임. 구차한 설명 따윈 필요 없음.
프로그래밍도 마찬가지.
코드를 보고 못읽으면 좁밥인거지 뭔 핑계를.
doxygen 있는 코드의 가치가 100만원 더 높다면?!?
잘 만들어진 코드들 보면 doxygen 내용이 그냥 함수명이랑 파라메터 읽은 수준.
가끔 return value case 에 따라 친절히 설명한 문서들도 있지만 솔까말 그거 enum class 로 대변되는 부분.
특수한경우나 사이드이펙트 주석에 달아놓으면 한 줄이면 되는거 코드로 보면 함수에 함수 따라가서 읽어야하잖아
글고 그게 꼭 필요한 경우보단 형식적으로 죄다 붙어 다니느라 코드 규모를 두 배로 늘린다는게 함정.
exception 도 클래스로 핸들링 하는 이유가 그런거잖아. 정 필요하면 코드화 할 수 있음.
doxygen은 개발자가 아니라 고객을 위한 겁니다.
그리고 그런 처리가 분리되는게 맞음.
ㄴ 아 그렇게 얘기하면 주석을 다느냐 마느냐 정도가 아니라 주석이 필요 없도록 코드를 짜야 한다는 거네
doxygen 문서 잘된거 읽어봐도 다 고냥 저냥 그렇던데. 이바닥이 그렇지 뭐 산전 수전 겪어보면 다 구차한.
식당 메뉴판이랑 비슷해.
하긴 API문서가 웹이나 딴걸로 뽑힐 때야 이쁜거지 그걸 코드로 보면 한페이지에 주석이 8할이더라
자기가 낯선 곳의 낯선 메뉴를 접하면 메뉴판의 글로 장황하게 적어봐야 사실 눈에 안들어옴.
오히려 코드보고 함정 있나 보려 할 땐 더 불편하더라
사진 한방이나 재료 아이콘이 나을 수준 ( 외국어보단 아이콘 )
그나마도 이식당 저식당 다 돌아본 사람들은 이름만 보고 다 알지.
메뉴판이 거추장스러운 부분.
C++ stdlib:
http://en.cppreference.com/w/
안드로이드 :
https://developer.android.com/reference/packages.html
ㄴ 이건 훌륭한 도큐먼트고 off-line help 인데, 주석이 아니잖.
https://api.kde.org/frameworks/attica/html/index.html
https://www.stack.nl/~dimitri/doxygen/projects.html
http://iphome.hhi.de/suehring/tml/doc/index.htm
http://www.alsa-project.org/main/index.php/Main_Page
https://www.cryptopp.com/docs/ref/
일단 QT 베이스라는데 거르고 싶지만, 가나다의 성의를 봐서 대답해줌.
Provider ProviderManager::providerByUrl ( const QUrl & url ) const Returns the provider with url base url.
Returns the provider with url base url 이게 설명임.
Provider ProviderManager::providerByUrl ( const QUrl & url ) const 이게 인터페이스임.
어느쪽이 정보량이 많냐? 솔까말 이런 설명이 독시즌의 대부분임.
정말 의미있는 경우는 10%도 안되는데, 그나마도 리턴값 타입 코딩 몇 라인 네이밍 조금 긴게 귀찮아서 설명으로 때운부분이 5% 넘음.
소스코드가 공개되지 않고 인터페이스만 공개하는 경우 별도의 문서나, 사용자 접근 수준을 낮출 필요가 있긴 하지 ( 그래서 고객을 위한거라고 지적한 부분이겠지만 )
그리고 예제 파트는 별도로 작성된거지. 그걸 다 코드에 때려박는건 미친거구.
결국 이러나 저러나 문서관리 비용은 증가할 뿐이야. 개발 다 끝났고 이제 인터페이스 첨삭이 없겠다 싶으면야 코드에 뭔 지랄을 떨어도 상관할 바는 아니지만, 거기서 뜯어서 다른 코드에 사용할때 또 문제가 됨. 결국 사본가지고 다루는거지. 정본은 남겨둔다는거고.
죄송합니다. 제가 doxygen 만능이론에 빠져있었네요. 역시 문서화는 사람 손이 닿아야...
https://v8.paulfryzel.com/docs/master/index.html
https://skia-doc.commondatastorage.g00gleapis.com/doxygen/doxygen/html/index.html
unibrow::Mapping< T, size > Class Template Reference#include <unicode.h>Public Member Functions Mapping () int get (uchar c, uchar n, uchar *result) Friendsclass Test Detailed Descriptiontemplate<class T, int size = 256>class unibrow::Mapping< T, size >
Detailed Description template<class T, int size = 256> class unibrow::Mapping< T, size >
디테일 디스크립션이 그냥 코드임. ㅋㅋㅋ
https://skia-doc.commondatastorage.g00gleapis.com/doxygen/doxygen/html/index.html
<- 여기 접근이 안되네.
독시즌이 바보같은게 뭐냐하면, 일단 클래스별로 트리뷰를 제공하긴 함. 사실 폴더 가면 파일 이름으로 유추되는 부분인데 말야. 개발툴의 찾기 기능도 잘 먹고.
그래서 세부 항목으로 들어가면, 몇 라인에 있는지 친절하게 알려줌.
코드를 수 배 불려서 라인으로 찾아가는걸 시궁창으로 만들어 놨기 때문에 몇 라인에 있는지 친절히 알려줘야 할 수준.
fuck 도 친절한거지 뭐.
대신 개행 한 줄 넣어도 문서를 rebuild 해야 하는건 안습.