How often to comment when passing code?

Question

What are the best methods for COMMENTS :

A bit of background.

• All our projects use version control (Subversion / SVN / Git),
• Most of them are affected by two or more developers,
• We use Springloops to host our version control, as it "just works" and has a higher level than having an internal developer,
• Since many of our clients have special settings, and since he works on setting up these environments for several users, we rarely work with the local dev environment. Most customers have a developer’s location in the cloud, and then in real time. Springlops is configured to automatically push EVERY commit to the dev server, and developers must manually click on live places.

Our policy was to comment on ALL that you do, but some of us have recently rebelled against this idea.

The problem with commenting is only twice, it works more and is less useful. Here are the problems we see:

• This encourages people to make comments that cover things that are already in version control (i.e. I changed line 42 to make blah). You can simply compare to get the same information!

• Alternatively, it will populate your comment stream with useless comments, which are a HUGE pain if you ever want to search for comments.

  • Margin issues in IE8
  • Other margin fix in IE8
  • Returning the latest patch and attempting to use something else with the brand in IE8

Any of these things just adds a lot of time and doesn't add any meaning. Comments are only useful if they are specific enough and rare enough that you can scan everything.

We were told that Git handles this more intelligently than Subversion, and we are open to change and obviously have a local development environment and only make lots of changes would also help, but based on our use, which is likely to be a net loss from the point view of efficiency.

I'd love to hear what best practices are for commenting commits, thanks for any feedback!

Answer 1

Git will not solve the problem for you; you need to answer this “simple” question: how can you add value to comments?

Some recommendations:

• Do not mention anything in the comments, which is obvious from the commit itself (for example, which line was changed). Modern tools will show a message of fixation and fixation side by side on the screen. It makes no sense to duplicate the work.
• Instead, explain why you made the change — this is usually not obvious. Was it a bug report? Include the error identifier. Was this something you found?

• If you often find yourself in a situation where you need to make several corrections in one commit, you need to learn how to focus. Do not follow every whim when changing the code. Do one thing, finish, do it. Then do the following.

  If you come across something, take a note (on paper or in an additional text editor that you hold in the corner of the screen). Do not always interrupt your work! Multitasking / recursive code editing has a major impact on the level of quality and stress.

You will still receive long lists of "Fixed IE8 Margin", but that in itself is not a problem. When you say “we want to find comments”, you should come up with a way to add useful information to the comments in order to make it reasonable to search. For example, always use the same format for error identifiers. Plain text is bad for searching, especially for capturing messages that need to be concise.

Just missing comments is not a decision, it is either laziness or a sign that he is a sociopath ("who cares if someone has a problem with this?") Or poor training ("I have no idea what to write," )

The first and last can be solved through training. The second is getting rid of risk (i.e., firing a guy).

No version control tool in the world can help you.

Answer 2

My philosophy is this:

• Block as soon as possible
• Update and build before commit
• Diff before commit
• DON'T PERMIT STORY: update after commit and test BUILD

All this is a matter of personal discipline, which every member of the team must follow. The build manager is “encouraged” to wake people up at midnight if they break the build.

Answer 3

My rule of thumb is that if I cannot summarize the commit changes in less than two sentences, that was too long after the last commit.

And As for what to write in this sentence, I never say anything specific or specific file, because this information is embedded in the commit. I usually mention specific changes in plain English, as I would explain to someone who was not part of the project.

This works very well because, whether I or someone else in a few months, they can read commit logs, like a story about how the project is developing. I even made blog entries that were just a copy and pastes of my commit magazines.

Answer 4

All checks should have a comment, but it should not really degrease the change itself. The comment should be a quick general comment about what has been changed, not the details of the implementation of the change, which, as you say, can be found in the change itself.