Best Practices in IT

Most of my IT career has been as a consultant and a manger of consultants. Over the years I have established some patterns to follow that I find helpful in making projects and technology easier in the long run. I sometimes share these in mentoring sessions and have heard often enough “you should write that down” where I started to.

I am still writing these concepts down, and while they originate from a consulting perspective they translate to every day practices beyond consulting.

At the time of this writing (not reflected by the pub date), I am re-vamping this site. Part of the update is moving this content from a standard page to a category page. The navigation will change to reflect that when it is either complete or well along.

Source Control Check-in Minimum Daily

January 5, 2023Scott S NelsonLeave a comment

Daily check-in of code is not optional for professional developers. There may be a rare circumstance where this is not the case, and such exceptions must be approved by the technical lead on the project on a daily basis.

An increment of work should seldom take longer than a day. All code that does not break the build should be checked in prior to leaving work for the day.

Code should be checked in each and every time it successfully builds and passes basic functional testing.

You should know the status of your own in-progress code at all times. If you don’t, then you cannot probably manage source control and the application is at risk for both difficult defects and issues during integration testing.

Accept that iteration 0 will suck

December 29, 2022July 23, 2023Scott S NelsonLeave a comment

While the definition of technical debt is…

…the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer. (https://en.wikipedia.org/wiki/Technical_debt)

the original cause of some tech debt is a combination of optimism and ego while following a best practice that should be expanded on. The best practice is to always keep code in source control to preserve work product in the event of hardware failure or accidental deletion (or the proverbial bus accident/lottery fortune).

The expansion this practice requires to truly be best is to use either a repository naming convention or a branch naming convention to indicate that source is the first iteration. The lack of this naming convention for initial commits leads to acceptance and defensiveness of early approaches that will often benefit from major refactoring if not complete abandonment.

Developers frequently avoid major refactoring for many reasons. In mature systems it can be a very real risk to do so and should be approached cautiously. However, the dislike of refactoring often impacts very early work where such changes can (and should) be done with ease.

Whether it is ego, optimism, laziness, deadline pressure, or a combination of any or all of the common factors, using naming conventions that make it clear that refactoring or replacement is expected will help to prevent early tech debt that will likely worsen over time.

The next level is to maintain and architecture decision log for the repository and require an entry to that log for any first iteration commits to reach a status where the code will be deployed. Reviewing these decisions periodically will help identify both intentional (assuming an exception log as well) and unintentional technical debt.

When in doubt, ask!

October 12, 2022September 7, 2023Scott S NelsonLeave a comment

(Feature image by nikko macaspac on Unsplash)

I have seen more problems tolerated for extended periods simply because no one spoke up about it.

One example that often comes to mind is a 9 month project that I joined in the middle. The first thing I discovered is that deployments took several minutes. I also noticed that the the development environment would frequently lock up for extended periods. This had a serious impact on my productivity. This being the days of products targeting the latest result of Moore’s Law, I set up the environment on my recently-built home computer that night and everything ran perfectly.

What had happened is that the project was the first with a new version of a platform our company had been working with for a couple of years. The new version was much more resource intensive. The team had been struggling with this impact to productivity for months, which was why they were adding someone to the project mid-way through (and were far behind schedule).

Once I realized the issue, I immediately brought it up to management. Because no one else on the team had brought it up over the previous months they assumed it was just me. So I told management that I would work from home until they provided the team with updated development hardware.

It took 6 weeks of my not coming to the office and out-producing the rest of the team by a huge margin for them to realize that 1) I was not kidding about it being intolerable and 2) the increase in productivity would more than pay for the hardware.

The folks that were struggling all that time just assumed that management was aware of their problem (and, worse, didn’t care). It made their lives unpleasant for months and cost the company 10’s of thousands of dollars because no one spoke up.

I get that sometimes people don’t want to bring up issues because they don’t want the attention, or don’t want to appear ignorant or needy. If you are concerned about that, just don’t ask in a meeting. Pull the person that can do something about it aside and ask them one on one. They will usually either have a good answer for you, or will do something to help you. If they don’t, look for the next person to ask.

#TIL: How to Present PowerPoint Slide Show in a Resizable Window

September 1, 2022October 21, 2022Scott S NelsonLeave a comment

Full screen is great if you don’t need notes. Until today, if I need notes I just minimized the tools and gutter while presenting. And then I discovered this:

Slide Show > Set Up Slide Show > Browsed by an individual (window)

My Pinned Wiki Post Template

July 21, 2022October 23, 2023Scott S NelsonLeave a comment

If you use this, please link to this blog post.

This is our Wiki

There are many like it, but this one is ours.

Our wiki is our guide. We support our wiki through comments and additions.

Without updates, our wiki will become outdated. Team members will become frustrated when information is missing or no longer correct. Being a good team member includes being a contributor to the wiki.

That cool reference you found that you will always remember? One day, when you need it most, you will forget it.

That awesome solution to a code or design issue that is perfectly clear and understandable now will look like a foreign language in 2 years (months, weeks, sometimes even hours). Add an explanation to the wiki.

When in doubt if something should be added to the wiki, add it. It can always be deleted later.

This is your wiki. Keep it clean but not too lean.

The Architect
(A serious parody of The Rifleman’s Creed )

(“Obligatory WIki Photo” by cogdogblog is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/?ref=openverse.)