News for hackers. Stuff that matters.
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?

Re:Cello: Higher level programming in C by Myrmornis on Thursday July 18, 2013 @12:44AM (#6061814)
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 :)