by Tdarcos » Sat Sep 28, 2024 3:19 pm
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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!"
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Disk space is cheap; you should be creating repositories (folders under source code control) for each different project you're working on.
- 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.
- Push commits to your branch (or main path if you're working alone) at least once a day.
- 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.
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
[list=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.
[*]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.
[*]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.
[*]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.
[*]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 [i]how[/i] the program does what it does (which the code will tell you), but [i]why[/i] 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.
[*]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!"
[*]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.
[*]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.
[*]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.
[*]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.
[*]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.
[*]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.
[*]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.
[*]Disk space is cheap; you should be creating repositories (folders under source code control) for each different project you're working on.
[*]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.
[*]Push commits to your branch (or main path if you're working alone) at least once a day.
[*]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.
[/list]