Personal Coding Workflow

Some thoughts on personal coding workflow

My coding is rudimentary at best but the lessons I have learned along the way save me from constant anguish.

When I first started coding I made all the basic mistakes. I failed to appreciate DRY (Don't Repeat Yourself [wikipedia DRY]( from the very beginning but only as an after-thought. I avoided version control and failed to document. Backups were far a few between and as a result I found myself repeating the same mistakes over and over again.

Let me just touch a a few of these things but I will start at the end and work back.

My current coding development approach is the have a working copy of my code outside of my repository. It took me a long time to understand how this offers benefits for my personal style. Sadly, I am a “force” programmer. Yes, I start with design and pseudo code, but not knowing all the tricks coding holds secret from the amateur coding hobbyist I found myself refactoring all the time. In researching how to code a specific routine I would learn a new “trick” and as a result have to go back and refaactor all the code that could benefit from that new “trick”.

When I have a code framework that is worthy of version control I build a git repository and check it in and push it to a remote repository. This gives me both version control and backup. But I keep a separate working copy of the code in my routine PATH. One of the problems I continually faced was when I did a check-in, my check-in messages were terribly vague and less than useful. So two things were needed. I keep a note file for the code project and treat it like a journal where I try to manually add changes I have been making to the working copy. Having a working copy means I can hammer on the code without fear of disturbing the version control copies. Wen I reach a stable working copy I will run a diff between the working copy and the repository copy and use a synopses of that diff as my check-in message combined with the project notes I have been keeping. So many changes occur in my code that I need both techniques to try and keep accurate commit messages. When I am confident that the working copy is stable and I have pretty solid idea of what my commit message will look like, I then copy the working copy over to the local repository, check it in with my honed commit message (which has a structure ie: scope, change_level, reviewed_by etc for each block of code touched). Then I will push it to remote repo (which in my case is usually a separate local server). If my working copy get broken (admit it, it happens) I can easily view the differences with the latest repo copy and either fix the working copy or start over with a copy of the repo copy. I used to make my code changes directly to the version control copy because that is what I thought would work for me. Using branches can help avoid issues but you can get lost in the swamp if you are making lots of changes.

Having automated workflow using scripts or tools is essential but don’t come naturally for me. But I have learned to use them (like vim ALE , linters, pre-commit hooks or scripts, document generators pydoctor for example etc). My workflow is now far more consistent than it was in the past and it is far more efficient. Let’s face it, as coders we are all about efficiency. My daughter asked me one time why I worked so hard and I told he “so I don’t have to work so hard tomorrow”.

So let me back up here a bit. Documentation was one of the first lessons and programmer learns. Coding can be complicated and so all your trial and error structures and attempts are lost to history as you refine your code, unless you properly document both your success and your failed attempts. Invariably your coding efforts stand on their own for weeks, months, or even years and then you back to work in the code again. Unless you have properly documented you will forget why the code exists the way it does and end up repeating old mistakes. So developers learn early to document.

Another lesson I had to learn was syntax and structure. I learned C language early in my coding journey and loved it but I wrote code blocks that lacked consistency so it was hard to learn. At first I avoided python because it forces a minimum level of consistent formatting. As the road goes you learn to appreciate the importance of consistent style in you code. Then I started using linters when ever I code (see vim and the ALE plugin). That forced me to get more disciplined in my coding style and as much as I fought it I finally learned to really appreciate it. To the point where I run a linter on my code before check-in and if it fails the linter it forces me to go back and review my styling failures (see git pre-commit hooks). My sanity is better for it.

As for the DRY principal, I am so much more aware of the traps now than I was in the early days. First, I know know to name your variables in a meaningful and consistent way. I had a project director who I loved working with tell me that she used to teach people on her team to “write it so it will run on the moon”. I understand what she was saying, your code has to be non-fragile (see Talib Nassim). There is only one way to get it there and that is to make it fit the DRY principal. If something breaks you one to be able to fix it in ONE PLACE. If you repeat yourself you will chase your own code right into Alice and Wonderland. But in order to get there you have to have practiced it for a healthy amount of time. Then you can “see” it coming before you find yourself there. Vince Lombard once said, “It is not practice that makes you perfect, it is perfect practice that makes you perfect”. Practice DRY all the time and it gets easier to see the need before you write the next line of code. Ultimately it forces consistent structure into your code. I used to find myself repeating lines of code and suddenly shaking my head realizing I have to go back, “functionalize” what the repeated lines of code whereas now I see how to avoid that before the code gets written (usually). It starts with make a well named, consistently styled variable name for pretty much everything. Often I would write a line of code not using variable name but rather stinging a steam of function calls together in one line. I was assuming that I would never need to write that line again …. but invariably you do repeat that line. That can be avoided many times by just establishing variable names right up front and assigning returned values to them.

I have read a good deal about the early UNIX developers and they exist as heros in my world. I learned that Dennis Ritchie and Ken Thompson developed the man page format for documentation for a good reason - consistence and well thought out design. One of the stories I read about had to do with the development of the file hiarachal structure/system and how they spend a few weeks designing before they started coding. That structure is still alive and well almost 50 years later. Design up front; it means everything - it avoids “moving furniture around in the dark”. Begin to document before you begin to code. The early pioneers had it right then and they still have it right now.

’nuf said… go code, and Enjoy!'

Geoff McNamara

"Do not meddle in the affairs of wizards, for they are subtle and quick to anger.” J.R.R Tolkien

Elizabeth City, NC