How to Write and Document Code So That Other Developers Can Understand It | Hacker News Reader

How to Write and Document Code So That Other Developers Can Understand It

thinkinghard.com

5 pointspjdorrell3 comments

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.

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

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.

Reply on news.ycombinator.com