Don’t comment bad code—rewrite it

In this post i will share my experience of "comments in code" that i have got by reading code , writing code and reading books.

Lets start with famous quote

“Don’t comment bad code—rewrite it.”
  —Brian W. Kernighan and P. J. Plaugher

Lots of comment in code looks just like above image and it is distraction.

Comments are lie 
Most of the time comments are not in sync with code, no one cares about it so no one maintains it.

Code is refactored
Code is under constant improvement, it changes , evolves and dies but code comments just sticks and become orphan.

Bad code has more comments
Once we write code that is hard to understand then we try to explain it by comments and it tells lot about our failure to write expressive code.

Noisy comment
Lets look at at some code+comment from public domain.

https://github.com/apache/hadoop/blob/trunk/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsAdmin.java

/**
	* Create a new HdfsAdmin client.
	*
	* @param uri the unique URI of the HDFS file system to administer
	* @param conf configuration
	* @throws IOException in the event the file system could not be created
	*/
	public HdfsAdmin(URI uri, Configuration conf) throws IOException {
	FileSystem fs = FileSystem.get(uri, conf);
	if (!(fs instanceof DistributedFileSystem)) {
	throw new IllegalArgumentException("'" + uri + "' is not an HDFS URI.");
	} else {
	dfs = (DistributedFileSystem)fs;
	}
	}

This code snippet is from popular open source java project, many comment in enterprise is also like this. This adds more noise than value.

Journal comments
Many scripting code, data base code, python code is based on this pattern, this looks like team has no trust on source control and they have taken over this responsibility. It looks something like below

/*
01-Apr-2019 - First version with skeleton code by someone
10-Apr-2019 - Config support added  by someone
....
...
*/ 

Marker comments
This starts with something like below

// Starting init

//Make DB call 

this is also very common in scripting, DB stored procedure or in real enterprise type programs. This patterns tell that it is shouting to extract small function but gets overlooked.

Commented code
I am sure you have seen this many time and got frustrated that why this dead code exists.
It looks something like this.

//Keeping this for backup
//fastCode()


superFastCode() 

Author code
IDE adds block of comments to every file that is added to project, it looks like below

/*

@Ashkrit
*/

Author names is just at the top of the file but he no more maintains it and does not work for team or organization but occasionally gets credit/blame for his creation.



Conclusion
Code Comment mostly adds no value, it comes between you and code, it is one extra distraction.It also promotes bad habit for young programmer because they think "adding comments makes code better".

In some case comments are useful when you are writing public APIs but still be careful on what you write, software engineers are smart they can understand if code does not have accidental complexity.

I will leave you with another famous tweet by Kevlin Henney

Uncle bob has whole chapter in Clean Code: A Handbook of Agile Software Craftsmanship about comments. I recommend to read chapter, it covers things in more details.

If you like the post then you can follow me on twitter.

Design pressure on engineering team ?

How many time you are supporting or developing system and felt it could have been better designed.

Move fast and break things culture in software has allowed engineering team to get product early to market but has created huge Tech Debt that team has struggled to come over.

Engineering team is put under feature pressure to get the things done and other important things are left as nice to have.

Important things in system are put as "Non Functional" requirement but in reality these are the requirement that are must for system to be functional in long run.

In real engineering project like civil engineering people are trained to think about 

• What material to use ?
• How many people it can accommodate ?
• When maintenance must happen ?
• Where are the emergency exit ? 
• How to evacuate in case of emergency ? 

But many Software system are build without thinking about basic Operations or Support requirement.

Software development has become trend or resume driven to use machine learning, Deep learning, latest java script , latest NO-SQL or Stream processing,Blockchain etc.

These cutting edge fails to delivery to basic engineering needs if no upfront thought is put in.

As a software engineer we have to think about Design Pressure as first thing. What are these design pressure ?

• How service executes ?

• What load it can handle ?

• It is possible to run it on developer laptop ?

• Is it possible to debug it ?

• How Coupling is used or Cohesion is used ?

• Does it support automated packaging or deployment ?

• Is it testable or maintainable ?

• Single responsibility or multiple responsibility ?  

• Separation of concerns ?

• Can you observe system from outside ?

• Does system has pipeline or chokeline architecture 

• What are system dependency or it needs whole world

• Does it capture metrics or you have to make a guess.

• Does it fit in your HEAD or you need BIG head or multiple HEAD

These are things that are very difficult and expensive to add later.

The reason why we don't look at these things first is because "We get bored" or "We like complex" or "We want to copy what google or facebook does"

Not every company has problem that google or facebook is facing so we should be careful in picking tools/tech that is used by big internet company.

I want to end with with "tale of two value" of software system.

Behavior 

Software developer are hired to build new features and stakeholders work closely to get this thing implemented. This is the "what" part of Software.

Architecture

If this part is done properly then Software remains "Soft" or it becomes Big ball of mud.

This is "How" part and engineer has to take all the responsibility of this. 

Both the value of system are important and urgent, but more focus is put on behavior because it becomes Urgent as soon as project starts.

If we ignore "Design Pressure" then system will become costly to develop & making changes will be impossible.

Let me know about your experience with Design pressure 

Programmer Oath

Uncle Bob is very famous for his ideas on Clean Code. He is very hardliner on Test driven development.

I am big follower of him and have read few books Clean Code , Clean Coder  written by him, i have become better programmer after reading his books.

I read Clean Coder few years back and felt that this book is must read for every professional software developer.

Uncle bob recently gave a talk The Scribe's Oath , that summaries the whole book in 1 hour.

In this talk he sets nice context before getting to real stuff. He talks about couple of Oaths for programmer.

Not writing harmful code 
He talks about harm software developer does by releasing defect , makes code harder for other programmer to understand. Software should be easy to change and anything that makes hard to change is harmful code.

Code that i will produce will be my best work
This is something that you are proud of.

Each release with quick , sure & repeatable proof that every element of code works as it is supposed to.
This is all the TDD, BDD, CI etc thing comes in. It is inappropriate to accept some level of defect.

Frequent small release and not impede progress
Holding code to yourself and not let anybody seeing it, holding on to big commit are few things that will impede progress.  Small releases are better.

Fearlessly and relentlessly improve the code at every opportunity and never make it worse.
Almost every software developer is slowed down by bad code , but we still continue to write bad code for some reason. We allow bad code to rot in absence of automated Unit test. This is where The Boy Scout Rule is useful . Automated test are really useful to keep this promise.

Keep my and my team productivity high.
Don't hold on the big commit, don't create test that takes hours to run.

Continuously ensure that others cover for me and i cover for them.
This one is interesting, he talks about working like sports team and handling situation when one of the team member is injured or down.
Pair Programming can be good tool to achieve this.

Produce estimate that are honest both in magnitude and precision, no promise without certainty
This is tricky one, most honest estimate is "I DON'T KNOW" but this does not work in real world and we fall in estimate trap and make false promise. He recommend to draw curve around uncertainty.
You manager will come to you and say that we need this in next 2 days , can you try ?
Your answer to this should be i am already trying and not holding back any extra capacity. You should say no, when it is not possible .

Never stop learning and improving my craft.
You have to keep on leaning new language, framework, library otherwise you will fall behind and have to become manager :-)
 
Links to some of Uncle bob talks that i found good

Effective Estimation (or: How not to Lie)
The Principles of Clean Architecture
What is OO really
SOLID Principles of Object Oriented and Agile Design