Software dev at Netflix | DC techie | Conference speaker | egghead Instructor | TC39 Educators Committee | Girls Who Code Facilitator | Board game geek | @laurieontech on twitter
I think comments are essential for code snippets that were hard fought. If it took you considerable time to design and implement, its worth explaining what is happening there.
Strong naming conventions and clear delineation of logic does not act as a substitute for a quick roll up explanation.
Future you, or anyone else, shouldn’t need to read the entire function (and any other abstractions) to know what the code is doing and controlling.
I write tutorials on my blog at www.lankydan.dev . During the day, I am a Platform Engineer at r3 where I work on Corda, an Open Source DLT/Blockchain Platform.
Are you only talking about longer functions / functions that are doing really complex stuff? Or do smaller / simpler functions also warrant comments?
Basically, how far do you think we should take this and at what point is naming no enough and comments need to step in?
I'm not disagreeing with you, I think I have actually been gravitating to what you just said. Although I do not document private functions to often and instead normally comment on inside if it is doing some funky stuff. Maybe that is something I should change.
Software dev at Netflix | DC techie | Conference speaker | egghead Instructor | TC39 Educators Committee | Girls Who Code Facilitator | Board game geek | @laurieontech on twitter
I think hard fought code that results in a simple solution doesn’t necessarily need a comment. But code that wasn’t intuitive to write is probably not intuitive to read, so that context and explanation is helpful.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think comments are essential for code snippets that were hard fought. If it took you considerable time to design and implement, its worth explaining what is happening there.
Strong naming conventions and clear delineation of logic does not act as a substitute for a quick roll up explanation.
Future you, or anyone else, shouldn’t need to read the entire function (and any other abstractions) to know what the code is doing and controlling.
How strong is your emphesis on hard fought here?
Are you only talking about longer functions / functions that are doing really complex stuff? Or do smaller / simpler functions also warrant comments?
Basically, how far do you think we should take this and at what point is naming no enough and comments need to step in?
I'm not disagreeing with you, I think I have actually been gravitating to what you just said. Although I do not document private functions to often and instead normally comment on inside if it is doing some funky stuff. Maybe that is something I should change.
It’s definitely based on personal discretion.
I think hard fought code that results in a simple solution doesn’t necessarily need a comment. But code that wasn’t intuitive to write is probably not intuitive to read, so that context and explanation is helpful.