You don’t need to be overly verbose in what you write in you comments going into major/minor versions, date of creation, what the weather was, etc, etc, you do need to find a format that accomplishes one goal…
Communicate the purpose of what you are doing.
Many times I have heard the following responses;
- If they don’t understand it, they shouldn’t be working on it.
- I speak differently than most.
- My code is written in a way that it speaks for itself and doesn’t need any additional wording around what it does.
- I don’t want to tell someone how to read my code because then they won’t need me.
- This is a waste of time.
I’m not going to go through all of these because to be frank – they are all bogus – the purpose of commenting, the only purpose, is to help the next person that comes after you that has to readily figure out what to do whilst under the same pressure that you were under when you had to first write it.
Translation: You are trying to help your fellow team member.
If you don’t want to help your team succeed don’t write any comments, if you do want to help your team succeed, write some quick verbiage on what you did.
You don’t have to use all the fancy tools that are out there, take five minutes, ask your team what they need and get it done.
You won’t realize how valuable they are (and how thankful you are) until you have to start working with a window like this (and yes, this is seven years late for an overhaul or simple discontinuation and forcing developers to work out of Visual Studio Code and simply use Dynamics as an upload repository – in which case why not just point it to a GitHub resource).
(Sorry that rant went a bit longer).