Explaining why a code's modifier should also be its committer [closed]

softwareengineering.stackexchange https://softwareengineering.stackexchange.com/questions/409206

Question

The context of this question is the early stage of introducing a VCS into an academic setting consisting of non-SW-engineers, largely unaware of modern best practices related to coding as a team. At the time of introducing the VCS, many projects already had non-negligible amounts of code (serving as the initial commits in the respective repositories).

Team member X, who spent a significant amount of time implementing a complex mathematical algorithm, and is the only one who really knows what's going on inside it, is reluctant to adopt VCS and instead prefers to distribute periodic snapshots of everything they worked on in a certain period of time, and have somebody else push it to the VCS. Whoever ends up pushing it, due to their inevitable lack of understanding of the modifications, has no way to split them logically into smaller (atomic) commits, and no way of documenting the changes other than "Changes by X from period Y" - resulting in one giant commit that spans many files. This of course defeats much of the purpose of VCS, turning it into little more than a file storage service.

I believe that person X doesn't bother with the VCS not because of malice or an inability to learn, but because they don't see the added value in this process. I would therefore like to explain to this person the significance of introducing modifications in small and well-documented commits, in the hopes of getting them on board.

We don't have a large team, develop concurrently, use automation or anything but the latest version of the code. Therefore, many arguments in favor of VCS aren't really applicable in our case.

The best reasons I could come up with are:

  • One day, somebody else will need to maintain/modify this code. The external documentation (i.e. article/thesis) and internal documentation (i.e. comments in the code) may not explain why certain implementation details are the way they are (e.g. default values). If some line was changed, and the change was properly documented, this can help avoid repeating old mistakes.

  • Unless you accompany your codes with the exact commit messages that should appear in them, information might get "lost in translation".

  • You're needlessly creating work for another person.

  • One or more of the reasons given as answers here.

What other arguments, specific to our scenario, can I use?

Was it helpful?

Solution

Personally I wouldn't even try to break a large chunk of code into lots of little commits. You're bound to end up with intermediate versions that don't work anyway. Just check the whole lot in in one go. The commit message isn't that important to most people; it's just documentation. What's more important is what VCS gives you:

  • A known latest version. If you just keep sending copies of the software to anybody you think is interested, pretty soon nobody will know what is the latest version, and they will end up using obsolete ones without knowing it.
  • An incremental backup system. If you do something stupid and delete your software, that's no problem. It's in the VCS. If you make a change that completely breaks things and you don't know why, and don't know how to repair it, just revert back to the previous working version. It's in the VCS.

It's being able to revert bad edits that is the big win for frequent incremental check-ins. There have been several times when I have made changes to a bit of code and broken it. But by the time I realize I have broken it, I don't know what to do to put it right again. And there have been times when I have mentally kicked myself for not checking in the last working version. You can waste hours removing all your edits, then re-implementing the changes you wanted to make.

OTHER TIPS

Your problem is that you hired a mathematician who is not a software developer, and who is either unwilling or unable to follow decent software development processes. And since nobody can understand his code, to develop decent software. That’s the problem that you have and that you need to solve. And your management needs to realise that if he decides to leave you are in an awful mess.

What you could do to increase your company’s bus factor is to hire someone who is a decent mathematician and a good software developer and let them unravel the code, bit by bit. Making it clear to the original developer that if he tries to work against this he will be history. Let the new guy do code reviews, and if the code is not accepted, it needs changing. Pay the new guy more and tell the old guy. Explain to the old guy why he is paid less: Because he produces mathematics, but not value to the company.

PS. Whether he commits any snapshots himself doesn’t make any difference to your problem.

Licensed under: CC-BY-SA with attribution
scroll top