3 ms·
The thing with comments is: You should add them for people that don't want to read your code line by line. I don't want to run my internal compiler in my head
by SchizoDuckie 12y ago
The thing with comments is: You should add them for people that don't want to read your code line by line.
I don't want to run my internal compiler in my head when i'm reading your code, so you better make sure there's at least a docblock above every function that describes in 2 sentences what it does so I can get a global overview of what the heck this file is doing.
People that suggest that 'the code is the documentation' are always forgetting that reading code is way more taxing on the brain than reading english.
- ARussell 12y agoThat is exactly why once should take the time to give meaningful names to their functions, classes, and methods. If you are having a difficult time doing it, your piece of code is probably doing too much. Split it into pieces that are more easy to name.
- SchizoDuckie 12y agoI already assume you are using meaningful names for functions, classes and methods, as any self-respecting programmer will do. I can completely live with a 50 line function that does magic in a legacy project, as long as I don't have to read through it. 'split it into pieces' is everybody's favorite argument, but nobody is going to pay you to refactor it. DOCUMENT IT.