Skip to main content

Meaningful Names - Code Review Checklist with Example

"Names are everywhere in software". "The hardest thing about choosing good names is that it requires good descriptive skills"[1]. In my previous post, I emphasized that we should take care our code, so now let's start with naming.

Issue
Original code
Revised code
Reveals nothing
int d; //elapsed time in days
int elapsedTimeInDays;
Difficult to understand
public List<Cell> getThem()

public List<Cell> getFlaggedCells()

Specific to programmers
accountList
accounts
Number-series
public void copyChars(char a1[], char a2[])
public void copyChars(char source[], char destination[])
Noise words (indistinguishable)
customerInfo vs customer;
accountData vs account
customer, account //distinguish names in such a way that the reader knows what the differences offer
Silly made-up words
class DtaRcrd02{
 private Date genymdhms;
}
class Customer{
 private Date generationTimestamp;
}
Poor name
for(int j=0 ;  j<34 ;  j++){
   s += (t[j]*4)/5;
}
int realDaysPerIdealDay = 4;
const int WORK_DAYS_PER_WEEK = 5;
const int NUMBER_OF_TASK = 34;
for(…)
Member prefixes
private String m_dsc; 
private String description;
Interfaces prefixes
IShapeFactory
ShapeFactory
Constructors with args
Complex point = new Complex(23.0)
Complex point = Complex.FromRealNumber(23.0)
//use static factory that describe the args
Form of colloquialisms or slang
eatMyShort()
abort()
Different methods name of different classes with same code base
fetch(), retrieve(), get()
get() //pick one word for one abstract concept and stick with it
Different class name in the same code base
Controller, manager, driver
Controller
The variable names are not clear when they are used alone in a method
street, houseNumber, city, state
//Solution 1: prefix addressStreet, addressHouseNumber, addressCity, addressState
//Solution 2: create a class Address

References:

Comments

  1. This is one of the best blog post on code review checklist. It is really very important to have best code review checklist to developers. Thanks for sharing.

    ReplyDelete

Post a Comment

Popular posts from this blog

My 2017 Review

Passion for System Design After finishing a one year project, my longest stable team (3 years) was separated into two smaller teams. Sadly, but that was a good chance for me to become a key member in my new team. My preferred skills is about system architectures; therefore most of the tasks of building the application structures are handled by me. In order to enhance my design system skills, I have spent much my time for reading books closely after work. These following books helps me a lot.
- Object-Oriented Thought Process | Matt Weisfeld
- Head First Design Pattern | Elisabeth Freeman and Kathy Sierra
- Java 8 in Action: Lambdas, Streams, and Functional-style Programming | Alan Mycroft and Mario Fusco
Junior Technical Architect I was requested to join a technical architect team (aka Team. Alpha) where I actually has gained experiences almost on interviewing candidates for my company (lol). Besides, I noticed myself must improve the skills of convincing people because I have had a …

AngularJS - Build a custom validation directive for using multiple emails in textarea

AngularJS already supports the built-in validation with text input with type email. Something simple likes the following:
<input name="input" ng-model="email.text" required="" type="email" /> <span class="error" ng-show="myForm.input.$error.email"> Not valid email!</span>
However, I used a text area and I wanted to enter some email addresses that's saparated by a comma (,). I had a short research and it looked like AngualarJS has not supported this functionality so far. Therefore, I needed to build a custom directive that I could add my own validation functions. My validation was done only on client side, so I used the $validators object.

Note that, there is the $asyncValidators object which handles asynchronous validation, such as making an $http request to the backend.

This is just my implementation on my project. In order to understand that, I supposed you already had experiences with Angular…

Strategy Design Pattern

For example, I have an program with an Animal abstract class and two sub-classes Dog and Bird. I want to add a new behavior for the class Animal, this is "fly".  Now, I face to two approaches to solve this issue:

1. Adding an abstract method "fly" into the class Animal. Then, I force the sub-classes should be implemented this method, something like:

public abstract class Animal{ //bla bla public abstract void fly(); } public class Bird extends Animal{ //bla bla public void fly(){ System.out.println("Fly high"); } } public class Dog extends Animal{ //bla bla public void fly(){ System.out.println("Cant fly"); } }
2. Creating an interfaces with method "fly" inside. The same issue to abstract class, I force the classes these implement this interface should have a method "fly" inside:

public interface Flyable{ public void fly(); } public class Bird implements Flyable{ //bla bla public void fly(){ System.out.println…

How did I start practising BDD?

At the beginning days I have practised TDD (Test Driven Development) with using JUnit, I approached that I should test methods belong to a class. For example:

I have a class with some methods:

public class A{ public void method1(){ } public void method2(){ } }
And then, I wrote some test methods to check the corresponding ones, for example:

public class ATest{ @Test public void testMethod1(){ .... assertTrue(...); ..... assertEquals(...); } @Test public void testMethod2(){ } }
After that, I know that a test method (ex: testMethod1) should just only tests one thing, so I decided to write more methods for each cases. It looks like the following:

@Test public void testMethod1_When_Case1(){ .... assertTrue(...); } @Test public void testMethod1_When_Case2(){ .... assertEquals(...); }
However, it was not a really good approach because it seems that I just focused on test the functionality of the method of the class. With TDD approach, I knew that I should test the…

Styling Sort Icons Using Font Awesome for Primefaces' Data Table

So far, Primefaces has used image sprites for displaying the sort icons. This leads a problem if we want to make a different style for these icons; for example, I would make the icon "arrow up" more blurry at the first time table loading because I want to highlight the icon "arrow down". I found a way that I can replace these icons to Font Awesome icons.


We will use "CSS Pseudo-classes" to archive it. The hardest thing here is that we should handle displaying icons in different cases. There is a case both "arrow up" and "arrow down" showing and other case is only one of these icons is shown.

.ui-sortable-column-icon.ui-icon.ui-icon-carat-2-n-s { background-image: none; margin-left: 5px; font-size: 1.1666em; position: relative; } .ui-sortable-column-icon.ui-icon.ui-icon-carat-2-n-s:not(.ui-icon-triangle-1-s)::before { content: "\f106"; font-family: "FontAwesome"; position: absolute; t…