Apr-28-2017, 02:54 PM
(Apr-28-2017, 06:03 AM)ndc85430 Wrote: I'm not a big fan of commenting code, because the only thing that tells you what the code does is the code itself (and the tests, of course!) - comments can be misleading (e.g. if they're out of date) and extra noise (I've seen lots of commented out code just left there in projects I've worked on). I much prefer code to be written in a way that makes the intent clear - by using good names and breaking things down into small pieces (like nice, small functions).This is all very good - unless you have a multi-threaded project. When you have to implement complicated decision-making logic. When you have to account for system limitations or write optimization.
The purpose of the comments - occasionally - is not to explain what have you done, but rather why you've done it that particular way. What are limitations and border conditions.
On the other hand - breaking code in too small fragments may muddle your intents more efficiently that outdated comments.
On an anecdotal side - I was once asked by a code reviewer to explain in comments Linux shortcut syntax....
Test everything in a Python shell (iPython, Azure Notebook, etc.)
- Someone gave you an advice you liked? Test it - maybe the advice was actually bad.
- Someone gave you an advice you think is bad? Test it before arguing - maybe it was good.
- You posted a claim that something you did not test works? Be prepared to eat your hat.