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?

  • 2
    see How do I explain ${something} to ${someone}? – gnat Apr 23 '20 at 11:44
  • 2
    If they are "not software engineers", but academic mathematicians working alone, and whose code is frequently negligible, and whose code nobody else can understand anyway, then why should they be aware of "modern best practices related to coding as a team"? I wonder whether you aren't attempting to invent a case where none exists, because "good practices" (and the administrative burdens that accompany them) in one context are not necessarily good practices in all. – Steve Apr 23 '20 at 11:58
  • 3
    I wouldn't give arguments. I would just present them with a fait accompli: "We are not going to accept any more snapshots, you must commit any work yourself" If you want to be extra diplomatic, wait for there to be a merge conflic, and phrase it as "we have no idea how to resolve this" – Caleth Apr 23 '20 at 12:02
  • 1
    Dev-iL, the problem you're describing suggests to me that the real problem is that you're giving software work to people who are not actually qualified by skill or experience to do it. Would you have your mathematicians, without a shred of exposure to engineering, build physical gearboxes out of metal to implement their algorithms? If you want reusable code, your department may have to retain an experienced programmer to work with the mathematicians to structure and document a proper algorithm, and impose the requirement of communicability. – Steve Apr 23 '20 at 12:42
  • 1
    Dev-iL, it's not the complexity of using the VCS which I'm describing as like gearbox manufacture, it's the complexity of writing software (a) when done as part of a team, and (b) which achieves reusability. The justifications for VCS arise naturally when writing reusable software as part of a team. The problem is your students aren't writing such software - they're writing their own code, alone, and you possibly regard the result as either trivially simple or else unfathomable. You can't justify VCS in those circumstances, because it adds no real value. – Steve Apr 23 '20 at 13:42

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.

  • I think the part about various people using potentially obsolete versions is highly relevant. +1 – Dev-iL Apr 23 '20 at 13:04
  • 1
    Some of my commit messages span paragraphs... that documentation is important... – D. Ben Knoble Apr 23 '20 at 13:32
  • @D.BenKnoble I must admit that I tend to go the other way. My messages can be as terse as "Fix for ticket #123". If you want to know what the problem was, look at ticket #123. If you want to know what I changed, ask the VCS. – Simon B Apr 23 '20 at 14:56
  • It’s about the why, not the what. Diffs show the what, sure, but not why solution a over candidates b and c that i tried or thought about. I learn from commit messages in projects when im in unfamiliar code—having blame right in my editor makes this really easy and useful – D. Ben Knoble Apr 23 '20 at 16:14

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.

  • 1
    I stand to be corrected, but I gathered from the OP that the mathematicians concerned are students of the department, not paid employees. – Steve Apr 23 '20 at 13:58
  • 1
    @Steve Yes, that is true. This is why incentives through differential pay are not really an option for us. Otherwise this is a reasonable advice that could be worthwhile in another setting. I mildly disagree with the claim that it doesn't matter who commits the code, because I believe once the person goes through the process, they'll start seeing the benefits better. – Dev-iL Apr 23 '20 at 14:06
  • @Dev-iL No, the commit is just extra work that the guy doesn’t want to do. He won’t see benefits. He doesn’t care about yesterday’s code. He also doesn’t see that he’s a pain for everyone else. – gnasher729 Apr 24 '20 at 7:42

Not the answer you're looking for? Browse other questions tagged or ask your own question.