The syntax of a C(++)-like language lacks the expressiveness to explain all sorts of things you need to know before you understand any nontrivial program, including the meaning and purpose of its abstractions, assumptions about what is going on in the rest of the program when a method is called, constraints on how mutually-dependent entities may interact, the possible ways the state of a program may evolve (it’s not just a disjunction of all the states each object, considered individually, could be in)… A design-by-contract language like Eiffel might help with explaining some of these things, but I’m sure it cannot cover everything. I leave the question of whether such information should be in code comments, or elsewhere, as an exercise for the writer (look up ‘literate programming’ for an approach once championed by Knuth.)
On the other hand, one has to assume a certain level of knowledge of both programming and the problem domain, or else writing the documentation would become an impossible task. Deciding what to comment (and how) is a matter of judgment that cannot be reduced to painting-by-numbers coding standards.
* * item2.1
# # item2.1
Welcome! OmniNerd's content is generated by nerds like you. Learn more.