|
At work, I have a standard to follow which, to my eyes at least, is quite ugly. At home, I follow my own personal standard which is not too different from that used in the Boost libraries. While I'd rather not have to, I think that using two different styles aids in my comprehension of others' code - to help "look past" the notation.
An honourable notion - and one I try to work to. One such idiom I try to keep is "The Code Is The Comment" - sensible naming and layout keeps it as close to English as possible; when that can't be done, add a comment.
However, I think that if you want to leave your program in a state suitable for a maintenance programmer to come along and understand it, you need documentation. Without it, it's only the maintainer's best guess as to the explicit semantics of your work.
Kas.
|