2 ms·
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?
by williamcotton 13y ago
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?
- Myrmornis 13y agoFunction/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 :)