
How to Write and Document Code So That Other Developers Can Understand It - pjdorrell
http://thinkinghard.com/blog/HowToWriteCodeThatOtherDevelopersCanUnderstand.html
======
mrlyc
What works for me is to write the code with a target audience in mind. That
target audience is someone who learned the language for one term in college
and doesn't know it all that well. The maintenance programmers have met those
criteria, except for one person who didn't know the language at all.

I write programs in pseudocode first then add the code underneath, keeping the
pseudocode as a comment. The code I've written from 1984 to the present day is
still quite readable, apart from a parser I wrote in Perl.

------
danso
Uh, I'm sorry...but I can't imagine it being fun to look at old code that
you've been able to ignore for six months straight, no matter how well it's
documented.

Ad I think the jury's out about writing tons of comments in the code. A full
test suite is much more useful and asker to maintain

~~~
memracom
A full test suite does not replace comments. Most comments are replaced by
well-chosen descriptive names for data and functions, combined with
refactoring to the point that no functions have more than a half dozen lines,
which means that the number of functions is much higher than normal in un-
refactored code. This means more function names, and even more variable names,
and those extra names provide additional documentation.

That said, however, most business code is there to serve a problem domain
which the programmers do not understand implicitly. It is very necessary to
provide the programmers with good documentation of the problem domain so that
they can write the right tests. Without this documentation, the test suite
will be crap and the programmers will be too scared to refactor the code. So
documentation is very important but it must be the RIGHT SORT of
documentation. As the brits in the audience will know, the WRONG SORT of
documentation will lead to utter chaos and BIG BALLS OF MUD.

