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

Popular posts from this blog

Safari (older than 14.1.1) rejects TLS connections of TURN with Let's Encrypt certificates

Summary We could not make a video call successfully on Safari older than 14.1.1. The call kept disconnecting for some seconds. We got the following error in Nginx’s log SSL: error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown ca:SSL alert number 48   Root cause The Safari didn’t trust our TLS certificates (certified by Let’s Encrypt) when establishing a TLS connection into our TURN server. It is a known issue that could be found at Bug 219274 - ICE does not resolve for `turns` relay candidates rooted in LetsEncrypt CA . The issue was just recently fixed (end of 2020), therefore old versions of Safari still meet the issues.   Solution In our development environment, we replaced the untrusted certificate with a trusted one. We will warn our customers about this issue in our installation guide. Technical explained WebKit is a browser engine developed by Apple and primarily used in its Safari web browser, as well as all iOS web browsers. The WebRTC of WebKit relied on ...

Why Agile and Scrum Matter

Changes is constant, software development as well. Do you know the development of mobile phones, starting from Motorola DynaTAC (1973) to Iphone 6 (2014). How about the software? The new versions are released with new improvements. Software is not always able to automatic repairing. Therefore, software should be changed frequently and we need responding to changes. source:  http://answers.microsoft.com/ In working software today, how about customers' collaboration or requirements? We ignore the fact that many customers don't know what they want . We ignore the fact that when they know what they want, they can't describe it . We ignore the fact the even when they can describe it, they often a proposed solution rather than a real need . We ignore, that a lot of customers g ive us a solution but not the problem . source:  http://accelerateddevelopment.blogspot.com/ And, in working process, earlier founded bugs are cheaper. Manifesto for Agile ...

JSF 2 - Dynamically manipulating the component tree with system events

Let's suppose we want to modify the metadata (attributes)  of elements such as render , requried , maxlength but we do not define in JSF tags. The manipulating components can be conducted in Drools  files, for example. How could we do? I think that is what we need to change something of component tree during JSF life-cycle. JSF supports event handling throughout the JSF life-cycle. In this post, I use two events: postAddToView for scanning components tree and preRenderView for manipulating the meta of components before rendering to GUI. I modified my own project from previous post for this example. This is my first further JSF trying out with the project as I said before. :) We define the tags f:event below the form - a container component of the components which we want to work on. The valid values for the attribute type for f:event can be found from tag library document  of JSF 2. <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" x...

Sharing a virtualenv across several Python projects using Pipenv

There is a standard library for all projects in Python. However, several projects don’t always have the same dependencies all the time. That is where virtual environments come to play. You can follow this official document to use two separated tools  virtualenv and pip to  fulfill that need. My preferred alternative is to use pipenv . Pipenv is easy to use and convenient. The following are my steps to make a shared virtualenv for my all projects which requires the same dependencies. Step 1. Create an isolated virtualenv. python -m venv my-shared-env Step 2. Create a symbolic link to the created virtualenv. cd project_1 ln -s ~/.local/share/virtualenvs/my-shared-env .venv I have encountered the following issue at step 1. FileNotFoundError: [Errno 2] No such file or directory: '{my_project_path}/.venv/bin/pip': '{my_project_path}/.venv/bin/pip' The root cause was I tried to create virtualenv by running pipenv install and renaming the generated virtualenv to ...