Recommendations for programmers

[Tdarcos]

I've sometimes responded to requests for suggestions or recommendations for (sometimes new) programmers. I've decided to put all of them together in one place for criticism and comment. These are things I have learned, some because I got burned because I did something different from what I recommend here. Lost files, lost work, boring rework, and

1. If you're developing a new project or a program to solve a problem, try to take a few moments to have a general idea of how you are going to tackle it. The more things you can think of now, the cheaper and easier it will be to implement.
2. Consider writing down a plan as to what you think you'll be doing to solve the problem. It is just a general list, organizing your thoughts will almost certainly make the job easier.
3. You are not perfect; you will make mistakes. Sometimes immediately, when you have a syntax error that prevents compilation, all the way to a mismatch with other code that "breaks the build" and you have to harmonize the parts. Sometimes it will be logic errors, or sometimes typos that aren't caught until later.
4. Chances are, even on a one-time only use program, you will need to do maintenance on it. Remember, "maintenance" on a computer program is "any change to the saved file." Until a program is retired, it is always a potential candidate for maintenance as requirements change.
5. If you're doing maintenance or enhancements on a new-to-you codebase, try to get to look at, if any, notes, records or documentation you can find on it. You want to not only know how the program does what it does (which the code will tell you), but why is it doing it this way (which only the documentation, or in-depth analysis of the code, will tell you). There are a virtually unlimited ways a program can be written to perform a feature or solve a problem. Any documentation will help. If it doesn't exist, consider creating it; if it does exist, try to keep it up date.
6. Programmers are notorious slobs when it comes to documenting code or keeping notes. Their attitude can be summed up with a famous movie scene where a Mexican bandito is being offered a badge, "Batches? Ve don' need no stinkin' badges!". Programmers have the same attitude about documentation: "Documentashun? Ve don' need no stinkin' documentashun!"
7. Try to be different, try leaving notes or comments in code explaining why you're doing things (don't explain how, the code should do that) for the next poor sucker err I mean person who has to do maintenance later. That person may very well be you.
8. Despite what some people say, I think leaving comments in code to explain things is a good idea. Comments can help, but don't rely on them, they may not be updated when the code changes. If you're working on a piece of code and the comment now has nothing to do with what the code is doing, even if you're not going to put in a new comment, remove it. Better no comments than inaccurate ones.
9. Sign your code: leave your name as a comment. If you're not proud enough of the code to leave your name behind, perhaps you need to rethink what you're doing.
10. There is no such things as an "unimportant" or "tiny" program unless you can just throw it together in a few minutes, retire and discard it as unnecessary after. And maybe not even then. Far too many simple programs end up being expanded to do other things.
11. If you're not already using one, start using a distributed source code management system (SCM) with version control, where everyone working on a project has their own copy and possibly a master copy to push changes to.
12. The SCM you're using must allow you to commit files, then later, if desired, be able to move backward to a prior condition of the file. I prefer Git, but if you have one you prefer, fine, use that. There are about four others I've heard of: CVS, Mercurial, Subversion (SVN), and GNU Bazaar. I recommend looking at all 5 when choosing one; you may find Git to be right for your needs, or one of the others may be a better fit.
13. If the project has more than one person working on it, each should work on a branch. This way, they don't have a problem or step over each other if they mistakenly edit the same file simultaneously. If you and everyone have not modified the same file(s), merging back to the main branch will be trivial. If not, a merge/diff tool is critical to harmonize changes. If you're working on Windows, I recommend TortoiseGit, it integrates into Explorer and provides visual confirmation of folders that under an SCM, and if it is up to date on commits. (They also have SCM clients for Mercurial and SVN.) I have found the excellent program WinMerge to be invaluable for comparing files and even folders for similarities and differences.
14. Disk space is cheap; you should be creating repositories (folders under source code control) for each different project you're working on.
15. Disk space is cheap. So are commits. Do them frequently. When using an SCM, do a Commit every time you make a change that successfully compiles. If you've gone down a wrong path, and you need to back out to a prior save, you'll thank yourself. When you've accidentally deleted one or more file(s), or intentionally deleted the wrong file(s), and your SCM recovers them, you'll again thank yourself.
16. Push commits to your branch (or main path if you're working alone) at least once a day.
17. Some websites use time-based one-time passwords (TOTP). You can install an app to do this on a phone. I prefer 2fast, it's open source, and runs on your computer. If you want to use GitHub, this is mandatory. I also recommend git-for-windows, when you need more precise control, it provides a command-line version of Git.

[Flack]

Noted.

[Da King]

25-30 years ago, I was asked to write something in a particular way that I disagreed with. I dont remember the specifics, but I know that I REALLY thought it was a bad idea, and that it was going to cause issues sometime down the line, and the fix/rework that it was going to take was going to be more painful than if we had just done it the right way in the first place. I documented very clearly in that program what my stance was, and why we should not be doing it that way, and "Don't blame me."

Many years later, after I'd moved off to another team, I had a co-worker reach out to me laughing. He explained that he ran across my code, read my comments, and proceeded to explain what a clusterfuck it had become, and if they had just done thing the way I wanted to in the first place, they wouldn't have had any issues.

I felt quite vindicated.

[Jizaboz]

Hahaha hell yeah! Stupid fucks

[Flack]

25-30 years ago, I was asked to write something in a particular way that I disagreed with. I dont remember the specifics, but I know that I REALLY thought it was a bad idea, and that it was going to cause issues sometime down the line, and the fix/rework that it was going to take was going to be more painful than if we had just done it the right way in the first place. I documented very clearly in that program what my stance was, and why we should not be doing it that way, and "Don't blame me."

Many years later, after I'd moved off to another team, I had a co-worker reach out to me laughing. He explained that he ran across my code, read my comments, and proceeded to explain what a clusterfuck it had become, and if they had just done thing the way I wanted to in the first place, they wouldn't have had any issues.

I felt quite vindicated.

I'll add to this to say I've had similar experiences, and there's nothing worse than being contacted years later for tech support regarding some script or program you wrote for yourself or at most, a small team. About five years ago I got volunteered to build a virtual machine image that ran DOS for a customer, except we couldn't use MS-DOS because (a) Microsoft has no way to sell or license it any longer, but (b) it's not technically freeware, meaning we had no legal way to use it. So, I built an image using the alternative, FreeDOS. The whole point of this exercise was to allow these customers to run a really old piece of software that only runs in DOS and accesses a proprietary serial device to program runway something at small airports. Oh, and the laptops they owned didn't even have serial ports, which meant we had to provide USB-to-Serial adapters. It took a long ass time to get all of this working and I documented everything. A few months later I changed teams -- I haven't looked at or even thought about that image in many years. A couple of months ago I was randomly contacted by some rando tech support contractor who launched into some questions as if we had been in the middle of a conversation I'd forgotten. When you've worked at the same place for decades you end up touching so many things that you can't keep supporting all of it forever.

[RealNC]

we couldn't use MS-DOS because (a) Microsoft has no way to sell or license it any longer, but (b) it's not technically freeware, meaning we had no legal way to use it.

Why not ebay? People still sell original floppies. If you have the original MS-DOS box, you've got a license.

[Flack]

we couldn't use MS-DOS because (a) Microsoft has no way to sell or license it any longer, but (b) it's not technically freeware, meaning we had no legal way to use it.

Why not ebay? People still sell original floppies. If you have the original MS-DOS box, you've got a license.

Because we needed thousands of licenses.