Re:Cello: Higher level programming in C
by williamcotton on Tuesday July 16, 2013 @03:04PM
(#6054042)
I'm curious, how do you document your code?
Or are you strictly in the camp that if it is machine-readable and works properly that you've done your job?
Function/method/class docstrings (sorry, my comment may have been misleading) to document the purpose/contract/API, terse inline comments for the implementation only when something is not obvious to a skilled developer. And of course carefully-chosen variable names. I'm not at all a fan of heavily commented code. It just adds more bytes to comprehend, more bytes to maintain, and worst of all a high probability than the code doesn't exactly match the documentation, which causes a significant mental load. Also sometimes leads to people showing off in their natural language descriptions of their code. Same for literate programming: I want as few characters as possible that I have to understand, with that statement appropriately qualified :)
+1 The more prose can be kept out of code the better.