Sins in any Software Development Project

This post is a collection of bad practices from my school projects. You can read this to learn about bad practices or treat it as a comedy about the subpar standards displayed by my school mates (some in fact have been professional junior devs at some point). In this post, I will also be offering solutions and the correct practices if any new developers are interested and bother to follow them.

Disclaimer: Some of the students I work with are a delight, but there exist others whom repeatedly displayed willful ignorant practices despite repeated coaching.

Additionally, this post is not "calling out" on anyone, all names will be censored and I will not be revealing any names or personal information. All screenshots included are factual, not-fabricated and unaltered (other than censorship).

If you find yourself making some of these mistakes, I hope you learn why they are harmful before learning and applying good practices.

To be human is to err. I make some of this mistakes occasionally too, but the point of this post is to identify and avoid making these mistakes. If this mistakes are happening on a per-commit or daily basis, then perhaps it is not human error.

1. Never commit broken code

Is it ever OK to commit non-working code?

Is it good idea to require to commit only working code? This commit doesn’t need to leave the repository in a working state as: ... we are in early design stages, the code is not yet stable.... ...

Software Engineering Stack ExchangeVorac

Often there are things such as CI servers hooked up to these branches and checking in broken code into dev could mess up everyone's branch and break the build. - user40980 (http://softwareengineering.stackexchange.com/), 2013

It’s Almost 2014 and We Are Still Committing Broken Code | kvz.io

Dispite testcases, syntax errors still find their way into our commits.

KevKevin van Zonneveld

it's almost 2014 and we are still committing broken code. This needs to change - Kevin Van Zonneveld, 2013

Committing broken code to the dev branch is generally unacceptable. Every single developer will branch out from the dev branch to work on their personal features. The CI server (if exist) often builds from the dev branch and run tests. Pushing broken code to the dev branch is an extremely irresponsible and foolish act, especially halfway through the development cycle. Imagine most developers on the team has to halt their work, wait for the fix before resuming their merge on the dev branch. It results in a lot of lost productivity and frustration.

Many of the students I worked with seems to have problems resolving merge conflicts. They often commit and push mid-conflict for some baffling reason.

I've discussed the commit above with multiple professional developers. They in-turned shared it with their team about this type of mistakes. Seems like everyone at any technical level agrees that these type of mistakes are easily avoidable and extremely unacceptable (I will show how to avoid them later in this post).

Excuses: "But Xing, people pushed broken code because"

• "This person is new to git"
  There are git clients with GUIs. If you don't know how to use git, the internet or your teammates are good resources to start with. Pushing code might be forgivable on the first 2 times, but not the 8th.
• "Calm down about the syntax error Xing, I was about to commit a fix on the dev branch"
  Commits on the dev branch should not break under normal circumstances. Missing semi-colons are not extraordinary circumstances. Always do a simple build before you push. No one will be happy if the code they freshly pulled is broken.
• "I thought the conflict was solved"
  Git allows us to commit mid-conflict, but it is our responsibility to check that the conflict is solved. One way is to simply follow through the entire merge process, not that hard.
• "Hold on, isn't it git's fault for allowing us to push mid-conflict?"
  No, flexibility is in-fact one of git's biggest strength. I'm pretty Linus Torvalds intended for git users to be responsible for their code. Also once again, if you bothered to run a simple build before you push ‍️🤷‍♂️. Alternatively,
  https://stackoverflow.com/a/5757537/6622966

✅ What is the correct way to handle this?

An extremely simple way to prevent this cluster of mess is to stash your changes. Stashing is a quick way to temporary hide uncommitted changes for a while. It reverts your head to the latest local commit. Before you push your commit to the git server and cast it in stone, always do the following:

1. Stash your local uncommitted changes
2. Build your project and run any tests you have on your latest local commit
3. Make sure there are no errors again
4. Push the commit to the git server
5. Pop the stash from step 1 and continue working

Stashing and popping your code takes less than a minute. You can also run builds and tests easily after the merge to make sure the new commit is not breaking. It is very easy to be slightly more responsible and not screw your entire project team over.

https://www.atlassian.com/git/tutorials/saving-changes/git-stash

✅ Use git hooks

Another advice offered to me was to set up git hooks on the git server. It is a great way to ensure that the code passes some basic linter or run some tests before being committed into the server without setting up a fully-fledged CI pipeline. It is a great solution if your team members are still getting used to good git practices.

https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

2. Always provide context for your questions

Allow me to use a fabricated but accurate example. "The image upload got problem" with zero accompanying context is not a reasonable cry for help. What image? What is the problem? Is it syntax, routing, the image compression plugin? How am I supposed to help you with a seemingly complex problem if you only offer one line of statement? And by the way, if you send a blurry and shaky photo of the stack trace, no one can see anything. We are software developers, learn to use the print screen feature on your computer.

And also, if I can find the solution to your problem within the top 3 results in Google, does it mean you didn't put in the effort into fixing your own problems?

✅ How to ask questions?

In my experience, for another developer to have any context about your bug or error, you need these 3 things in some form:

1. The state you are trying to achieve
2. How you are implementing this feature
3. Any error logs or code that are relevant

Sometimes, the nature of the query means that you cannot find a solution on the internet. For example, clarifications about the system design, internal tooling bugs or unexplained test failures. In these scenarios, it is even more crucial for you to put in the effort into providing context and allow the other developer to understand your problem.

3. Never use nonsense variable names

Why will anyone name their variables like this? The object holds more information than the id. In fact, it holds all of the information about the object because it is the entire object instance. Calling it id is not only inaccurate, it is also like shooting ourselves in the foot when we need to refactor this in the near future. How about giving it another name like, I dunno, roomService, just like what everyone learns within their first hour of learning Java? Just because school examples use variable names like r or j or p, it does not mean that we should follow them.

Remember Furniture table = new Table(); ?

4. There are standardized good practices and there are your personal opinions

Never confuse your personal opinions with good practices. When we discuss code alignment, I prefer 2 spaces, but tabs provide easier alignment for developers who are visually impaired. My personal opinion is not aligned with what I think is excellent practice but I should not let this affect my decisions when writing software.

• "Never push broken code to dev" is not my personal opinion, it is a standard practice that helps every member on the team.
• "Pushing custom folding regions into dev" is bad in my opinion, but if it floats your boat and aligns with the policy (if any) of the team, then do it.

TL;DR

1. Be considerate and never push broken code to a branch where everyone will be collaborating from.
2. Ask sensible questions with good context.
3. Use intuitive variable names and follow sensible coding ethics.
4. Never confused our personal opinions with good practices.

Photo by Danya Gutan from Pexels
Man Reading Burning Newspaper