Is your code creating a hostile work environment?

You run a serious, grown-up business, with an HR department and everything. If you find out that one of your employees is making rude, off-color comments in meetings, you're going to deal with that immediately. It's unacceptable behavior, it's not okay for that person to make your other employees uncomfortable in their place of work. It's your job to make sure they feel comfortable and safe enough to do their work¹.

Likewise if that employee is making sexist remarks, or using racial slurs, or wearing t-shirts with sexually explicit images, or actively threatening co-workers with violence, or a whole host of other inappropriate behaviors. If you became aware of that, you'd do something about it. If you had a new hire starting this week, and one of their first encounters with their new coworkers was any of the above, you'd be mortified.

Now imagine that same employee opened up their code editor on the first day, started digging in looking for the cause of a bug, and during the course of reading the code they encountered all of the above.

If you're a veteran programmer reading this, you might already be nodding your head. If you're not, let me explain.

How can code be offensive?

The main culprit is usually code comments. Comments allow programmers to annotate computer code with human-readable text. It might be a plain-language explanation of an algorithm, notes on how the code works, notes on other things that didn't work, possibly even diagrams.

But comments are also a place where programmers can express frustration, possibly in very colorful and inappropriate language. That frustration might even be directed at coworkers, and might include threats of violence (probably meant in jest). Or they can leave Easter eggs for other programmers to find, including jokes, stories, or pop culture references. Which, depending on the programmer, may not always be appropriate for all audiences.

Another area where programmers might get inappropriately creative is in variable naming. Aside from a few rules, most programming languages allow a lot of leeway in variable names, and the computer doesn't get offended if the coder uses a swear word as the placeholder for a database query result. File names in a project might also get this treatment. Really, any place where the name of something only matters to humans and not the machine, there's room for abuse.

Does this really happen?

Yep. It happens embarrassingly often in software development. (Be warned, some of those links are to Reddit discussions; exercise appropriate caution when reading them.) Sometimes it's the result of immaturity or a "tech bro" office culture. It may not even be a local problem - maybe you've acquired another company's code base, along with both its technical and cultural issues. Or it may be totally unintentional - developers might not realize that the language and terminology they're using is potentially offensive. Or it can be the result of language differences².

Whatever the reason, your current team (and any new hires you hope to make) will be living in that code environment. If it's hostile, it might lead to good talent leaving. It might bleed into your non-code work environment. It might even lead to legal issues.

How do we prevent this?

If your code is purely internal, simply making sure you have a company policy about language use in source code may be enough - most programmers will avoid offensive language in source code if they know it's not acceptable. If your code is open source, and outside contributions are allowed, then a code of conduct is also a good place to specify that inappropriate and hostile language in source code is unacceptable. This is doubly important in open source, because anyone can see what is being written - the source code is now a very public representation of the company³.

I'm not a programmer, how do I determine whether this is happening?

Explain your concerns to your existing development team and ask them whether they see these sorts of problems (offensive/racists/sexist language, threats, or other inappropriate content) in the code. If it's code they work with regularly, it's likely they'll be able to tell you right away whether you have a problem.

If there are parts of the code that your team isn't familiar with (e.g., inherited or acquired codebases, legacy systems), an outside audit can surface these sorts of issues. Outside perspectives can also be useful for bolstering arguments with management⁴ about whether resources should be spent addressing a problem like this.

Conclusion

If you're a programmer, make sure your code and code comments are welcoming to your colleagues. If you're a manager of programmers, make sure that you've established expectations of reasonable and appropriate conduct in the code your programmers are writing. And if you're in upper management or HR, make sure that your company's software source code isn't a legal or talent retention liability.

---

1. Or you just care about not being sued. That's better than nothing, I guess.↩

2. I had a colleague once whose first language was Portuguese, and would sometimes mistype "tests" in code as the Portuguese word. It's only a one letter difference and an innocent mistake, but some folks might be offended.↩

3. Some programmers seem to forget that front-end web code (the HTML and JavaScript used to make web pages interactive) can also be seen by anyone who selects "View Source" on the page. I've seen more than a few JavaScript comments that would warrant a visit to HR.↩

4. Or your programming staff, if they seem to think this sort of thing is okay and doesn't need to be addressed.↩

Is It Time to Rewrite Your Code From Scratch?

Congratulations! You had an idea for a business. You hired a few software developers to implement your idea. You got your product out the door or started offering your service to the world, and it took off. Now that you've got a successful business up and running, it's time to think about growing and maintaining it.

Now you're faced with a crucial question: do you try to grow and maintain the version of your software that you already wrote, or do you throw it away and rewrite it from scratch?

It can be a tricky question, especially if the team which initially built it isn't around or if they're inexperienced. If you were in a hurry to get to market, you may have incurred a lot of technical debt. You may have hastily added and removed features as you learned more about your problem domain. Maybe you had to hastily on-board some new developers or consultants toward the end of the project to meet your deadlines. None of these are incorrect decisions, but one of their side effects may be a code base which is kind of a mess. And now you're wondering if the best course of action might be to rebuild everything from the ground up, cleanly, without the blind alleys and vestigial features.

Or maybe what you're operating off of now was a prototype that the original authors never intended to put into production; a proof-of-concept that isn't architected to be stable or scalable. You hired some developers to prove that your idea was workable so that you could take it to investors; now you're wondering whether you can turn that prototype into a production system, rather than incurring the costs of rewriting it.

If the code base is a completely unmaintainable mess, scrapping it might very well be the best course of action. But there are some pretty strong arguments to be made against throwing it all away and starting over. That messy code base has a lot of knowledge and bug fixes packed into it. But all that knowledge might be useless if it's inscrutable to new developers, or if the code is so tangled and brittle that making changes is difficult, risky, or simply impossible.

What you really need to know at this stage are two things:

• How maintainable is it?
• What will it take to make it maintainable enough?

If the original developers are still available and they are sufficiently experienced, they can probably give you an honest answer to those questions. I say "probably" because developers are human, and subject to human foibles. They can be overly optimistic or pessimistic because they're too close, too emotionally invested in the software. Or they may simply be loathe to admit mistakes. Or they may be overly eager to start from scratch and "get it right this time".

If the original developers are gone, or if they're simply not very experienced, you may just not have anyone in your organization who can accurately answer these two questions.

This is where a third-party code audit comes in. An unbiased assessment of your code by someone who has no agenda, no attachment, no stake in your decision. A code audit can tell you whether or not you have maintainability issues and recommend a course of action to correct any you may have.

Once you have that, you can make an informed decision about whether or not it makes sense to start over to or to continue with your current code base.

Interested in a code audit? CodeWise can help!

Do We Even Want This Code?

Your company just acquired a start-up; your business unit is absorbing another in the big reorganization; your tiny but successful company just got bought by a mega corp. Whatever the reason, you're suddenly looking at a bunch of code that your group didn't write, and wondering what to do next.

Should you carefully integrate it into your own code base? Or should you rewrite it from the ground-up? Is it a well-written, well-architected system that will be trivial to merge with your own? Or is it a big hot mess that you'll have to spend months untangling before you can even start adding new features?

You're suddenly looking at a bunch of code that your group didn't write, and wondering what to do next.

If you're not a programmer yourself, you may not know. If you're a current or former programmer, you may have already made up your mind - but you still need to convince your managers. Either way, an independent code audit is a good place to start.

A code audit can give you an idea of the level of technical debt you'd be inheriting by taking on this code. It can give you the reassurance that this code won't seriously disrupt your plans, or the warning that you should just scrap it entirely. Of course, it's possible that you haven't been given any choice - the word has come from higher up that you will be using this code. In that case, it might be worth doing a code audit so that you know what you're getting into. You might not be able to say "no" to an incoming mess, but you might be able to get the support you need to make phase 0 into a major cleanup and refactoring project. At the very least, it'll help you decide how best to allocate your development resources.

And if you're in the rare situation of having multiple code bases to choose from (e.g., "which of these two companies should I buy in order to acquire their intellectual property?"), a code audit can help you decide which one is the right fit for your circumstances.

Interested in a code audit? CodeWise can help!

Copy-And-Paste Code vs Maintainability

Code Reuse

When writing software, many of the various tasks we want the software to perform are similar. Writing data to the database is a good example. In one place the software may be writing recipe data to the database; in another, the software may be saving contact data to the database. In both cases, the bulk of the code is nearly identical (the only things which change are the actual data fields).

Rather than rewrite the code for modifying the database from scratch each time we encounter this problem, we write the code once and reuse it each time we need to make database changes. This saves time and is less error-prone (since rewriting that same code from scratch would quickly get repetitive, and bored programmers are more prone to typos and omissions).

There are multiple ways to accomplish this reuse of code; the most common is to create a code library which can be referenced anywhere in the application where we need to accomplish the particular task. In this example, the code to write data to the database would be made into a library and both the recipe form and the contact info form could use the code from it. Using a library for this purpose has an important advantage for maintainability - if a bug is discovered in the code for writing data to the database, that bug only needs to be fixed in one place (the library) and every other portion of the code which uses that library will now be fixed.

Copy-and-Paste

"Copy and Paste" coding is a technique wherein a programmer reuses code by literally copying it from one file and pasting it into another, sometimes making small changes in the new file.

A programmer might do this for any number of reasons:

1. The programmer doesn't know that other options exist.
2. The programmer is not sufficiently skilled to convert the code into reusable library code.
3. The programmer is rushed (making code reusable as a library is not as fast in the moment as copying and pasting).

Impact on Maintainability

This kind of coding has a huge impact on the long-term maintainability of the code base. If a bug is discovered in the code being copy-pasted, that bug now has to be manually fixed in every single place the original code was reused (rather than being fixed once in a library). This can be error-prone, as each instance of the copy-pasted code has to be found and modified by human beings. There's also the danger of simply missing one or more places that the buggy code has been reused; a typical symptom of this is having a bug which was thought to be fixed pop up again at a later time.

This same problem applies to new features and enhancements - for any changes which need to be made, all instances of the original code which have been copy-pasted have to be found and modified manually. This is a slower and much more error-prone process than simply updating a single library.

There's an additional impact to maintainability when bringing in new developers to work on the code - the new developer may not be aware that the piece of code they are working on has been duplicated throughout the code base. The new developer makes a change or bug fix in one instance of the copy-pasted code and none of the others - now the various copies are beginning to diverge, making them harder to track down for later changes.

Do Your Developers Use Version Control?

What is Version Control?

Version control software is used by programmers to keep track of all of the changes made to source code over time. There are many different version control tools available; which one a programming team uses may depend on the type of project, corporate policy, or simply personal preference. Popular version control tools include Git, Mercurial, and Subversion. They all accomplish the same goal, which is to allow programmers to safely develop software without having to worry about losing code.

What are the benefits of Version Control?

For programmers, version control allows them to safely experiment with features and bug fixes without the worry of breaking the existing code or losing any previous code:

• Because version control stores all of the changes made to the code, the programmer can always get back to any version of the code. The programmer can try something out and, if it doesn't work, they can simply revert their changes. This is especially important if they need to make changes to several source files; version control means they don't have to remember exactly what they changed and in which files. More importantly, it makes it difficult to accidentally leave something changed which shouldn't be.
• Because all changes are tracked, it's easy to figure out when and how a bug was introduced into the software. Programmers can just to see what's changed since the last time things worked properly.
• Because all changes are tracked, programmers never have to worry about losing code; if it was ever checked into the system, they can go back and find it. This means they can learn from past code; it also means that they don't need to worry about keeping code around which they might need in the future.

For everyone else, version control also has benefits:

• Because all changes are tracked, it's easy to go back to the previous version of the software. This is invaluable when someone has accidentally introduced a bug into the software; it allows the last known working version of the software to be deployed with relative ease.
• Because the entire history of the code base is available, it's much easier for new programmers to come up to speed on how the code works. This is invaluable for onboarding new programmers or hiring new contractors.

Should my software be under Version Control?

Yes.

But...

There are no 'buts' on this topic. If you develop software, your software needs to be under version control. If your programming staff does not use version control, they need to start. If the contractors you employ to write your software don't use version control, you need to find new contractors.

Programmers working without version control are like doctors who don't sterilize their equipment, or race car drivers who don't wear helmets. It's needlessly risky to the point of irresponsibility. Version control is as fundamental a software development tool as a compiler or code editor. There is no reason not to be using it. Not even cost - the three tools mentioned above are all free.

But my 'software' is just a website...

Version control also applies to markup files (e.g., HTML documents), stylesheets (CSS files), scripts, any part of your website or application which might change over time. All of these can and should be under version control.

Commented-Out Code vs Maintainability

Code comments are lines of source code which are added by humans in order to explain what's happening in the code to other humans; the compiler ignores these lines entirely when building the program. How comments are delineated depends on the language, but many languages (including C#) do this by prefixing the line with two slashes "//".

In the process of writing and debugging code, it's not uncommon for programmers to temporarily "comment-out" lines of code (or even entire sections) by prefixing them with "//" in order to narrow down the location of problems or to experiment with different approaches. In ideal situations, the programmer cleans up these commented-out lines when finished. On occasion, a programmer will forget and some code will remain commented-out which should have been re-enabled. If this results in a bug, the fix is usually as simple as un-commenting the code.

One common use (or rather, abuse) of comments is as a feature switch. In other words, instead of creating a mechanism to enable/disable a feature through normal program configuration, the programmer simply comments out the code for the feature. Re-enabling the feature requires that the code be changed and the application rebuilt.

Another common abuse is to enlist the comments as a way to retain code which the programmer may want again in the future. Perhaps the programmer is working on a fix for a bug and needs to make changes to some code. The programmer doesn't want to lose the old code (either because it may be useful somewhere else, or because the fix may not work and the code may need to be put back into its original state). So the programmer simply comments out the old code, leaving it in the source code file to be found later if needed.

Both of these abuses can lead to long-term maintainability issues. The problem is that a programmer new to the code (or one who hasn't seen the code in question for a while) can't necessarily tell why a particular piece of code is commented-out. Was the code accidentally left commented-out? Was the code intentionally commented out to disable a feature? Is the code simply an older version of an algorithm? Was it a forgotten debugging attempt? Is it being left in for historical purposes?

Additionally, this (possibly) vestigial code makes the code less readable and pollutes search results for programmers who are trying to find particular code when debugging.

Both of these uses for comments have better alternatives. Switching features on and off should be done by the application's configuration mechanism; this makes it easier for the feature to be turned on and off (since the code won't need to be modified and rebuilt) and removes any confusion as to why the code is commented-out. Experimenting with a solution which may need to be reverted and keeping older implementations in case they need to be used again in the future are both problems which are solved more efficiently and safely by the version control system.

Typically, large swaths of commented-out code in an application's code base are a symptom of larger problems with version control. It can mean that version control is not being used at all, or that the programmers working on the application do not understand how to use the features of the version control system. It's closely related to the problems with code bases having sub-folders and files with labels like "BACKUP" on them - programmers are experimenting with possible solutions to problems without a safety net in place.

When commented-out code is polluting a code base, the solution is actually very simple. Place the code under version control and delete the commented-out code. If you ever need the commented sections again, you can always retrieve them; if not, they're out of your way.

Do You Have the Right Software Development Team?

There are literally millions of programmers in the world. How do you know that the ones working on your software are doing a good job?

When things are going well, it's easy. If your customers are happy, your projects are on schedule, bugs are rare and quickly dealt with, and new features are being implemented in a timely manner, then chances are you've got a pretty good team.

But what if things aren't going well? What if you're getting tons of bug reports, and bugs are going unfixed for a long time? What if all your new feature requests take much, much longer than you expect? What if all of your projects are running behind schedule?

Your software team may be telling you that the features you're requesting are particularly difficult, or that the bugs being report are particularly hard to track down, or that external circumstances or lack of resources are putting them behind schedule. And the thing is, they may be right. This is one of the challenges of being a non-technical business owner or manager: "How do I tell the difference between 'our problems are difficult to solve' and 'our software developers are not good'?"

If you're not a programmer yourself (or if you've been out of the trenches and in management for a while), you may not feel qualified to judge the work of the programmers you've hired. Or you may simply feel more comfortable with an outside opinion. Either way, a code audit is an excellent way to determine whether you're in the "hard problems" camp or the "we hired the wrong people" camp.

And the answer might be somewhere in-between. A code audit can point your team in the direction of improving their code so that all of your problems become easier to solve. Whatever the situation ends up being, you can't make a decision until you have the information.

Interested in a code audit? CodeWise can help!