At one point during my Flatiron Boot Camp journey I realized my code commenting habits were getting a little idiosyncratic, to put it diplomatically. I expressed some mild concern about this to a number of friends, since I do have a number of friends who are programmers or project managers. I received, for my concerns, a Wayback Machine copy of a set of github statistics on profanity in commits. Nice to see I’m not the only one leaving bleepy notes in my code! Variable hilarity of saying the f-word in your comments aside, it made me think about my code commenting and commit habits.
I’ve been programming for so long that many of my foundational habits were formed in the dark recesses of childhood from which memory is dubiously retrievable at best. I do know that my habit of giving each section of code an all-caps label describing what goes in these ten lines of code (or fifteen, or five, whatever constitutes a section) comes from the early days of designing HTML. There were fewer tags to differentiate the purpose of this or that section then, so comments describing the purpose of each section of script with an index at the top was helpful for Ctrl-F purposes. And I did write a lot of code that involved a header, a menu bar, a pile of text, a footer menu bar. Sometimes a disclaimer stating that I didn’t own these characters, please don’t sue me Chris Carter.
Getting deeper into boot camp meant learning new programming languages for the first time in years, beginning to functional program end. Although the underlying logic of the languages remained computer logic, some of the syntax and a few of the commands were very new. So in addition to my section comments I began to add instructional comments after every two to three lines of code, so when I went back over older labs I understood why this command was formatted this way, what this other command meant and what it referred to, what the expected output at this point in the code was, what return value I was getting and what return value I was looking for. It’s harder to remember to do this now that I feel more fluent in Ruby and JavaScript, but I try to keep in mind that five years in the future I might not have touched Ruby or JavaScript in all that time, and I might want to remember what’s going on here.
Commenting code is not a skill I learned in Flatiron School. I think it should be. The internet and technology in general being what it is today, no one programmer can be expected to maintain a system or a program over the course of their lifetime and, when they retire, to train just one person to follow them. Everything is interconnected and everything builds off of someone else’s work. To be a polite, kind programmer we should all learn how to write clear, concise notes in our code so the devs following us can understand what we were doing and where we were going with this code. Maybe line-by-line and command-by-command is a bit much if you’re not actively learning that language, but where data is being taken from and what return values or type of return values you’re expecting should be a part of that commentary. Explain why these files are imported and exported, what data or functionality they’re providing, and if the file is large enough add in a note once you reach that point of intersection where the file was imported from again, to minimize scrolling up and down.
In addition to the commenting I start every app with two markdown files: project notes and a dev log. The dev log is a day-by-working-day log of everything I’ve done, including sometimes notes on what version of a gem I installed or what packages I installed in what order, mainly to keep track of what I’ve done but also when necessary to indicate that some steps should be done in a specific order if I or anyone else wants to duplicate the app to a certain point.
The project notes file is mainly just a neat one-stop shop to keep my to-do list, my bug list, and my base project architecture. And since it started with writing apps for the Flatiron School boot camp, it includes sections for requirements (although now requirements might be more accurately ‘initial design goals’) and stretch goals. The to-do list includes brief notes on bugs I may find, notes about reframing that needs to happen, style details to clean up, and other small fixes to make. As I clear it out, I migrate the stretch goals to the to-do list one by one.
I don’t know that having a dev log on every app would be helpful to everyone following in that programmer’s footsteps, but I find them useful. And as I said earlier, I like taking apart programs to find out how they fit together.
The project notes, on the other hand, should also be taught as a basic one- or two-reading insert in coding boot camps. I wish I had a set of instructions and a few samples to show me how to make a clear, useful Readme document! Writing is a skill often referred to as a “soft” skill, and equally often overlooked in career tracks and educational courses of all kinds, not just tech. However, communication is a vital skill in any workplace. That extends to writing an email that’s both polite and includes all relevant information, writing an instructional pamphlet for a device or piece of software, or writing commentary and commit messages in computer code. The profanity can be fun and reassuring to know you’re not the only one struggling with this particular piece of software, but it doesn’t help if you finish reading through the code and you’re still as confused as you were when you started.
Keep it concise, but make no assumptions as to what your reader knows. It may help to talk through your code as if you’re rubber-ducking it. State your intentions, but also state what your tested results are at each step, so a person following you can tell when the results they’re getting are indicative of broken code and narrow down the source. And don’t sweat the f-bombs, but do follow up every ‘what the ffffff’ with an explanation of what the problem is so, if nothing else, when you go back to debug it you’ll have a clear idea of what the problem is and you won’t be repeating discoveries you made already.