Writing Maintainable Codes

Submitted by: 

When working on a project where in you have to add features to an existing code written by other members of your team, you may have encountered problems understanding parts of the code. Sometimes the problems are caused by codes not well commented or sometimes the codes are simply unreadable.

Take this code for example:

  1. int x = Integer.parse(request.getParameter("x").toString());
  2. switch(x)
  3. {
  4. case 1:
  5. ...//
  6. }

The code is well structured except for the fact that the variable name "x" doesn't explain its purpose. One of the conventions to follow in writing variables is that you must name your variables words that describe its meaning.

In this example, if the programmer intends to use the variable "x" for evaluating where the current user will be redirected, he may use a more meaningful variable like:

  1. int redirectPageKey = Integer.parse(request.getParameter("redirectPageKey"));
  2.  
  3. ...

This way, the programmer who will maintain the codes could easily understand what your code intends to do.

Another thing is to write descriptive method names:

Instead of:

  1. public int calculate(int num1, int num2){...}
  2. public void fillList(){...}

Use something like:

  1. public int getSum(int num1, int num2){...}
  2. public void getStudentList(){...}

By writing readable codes, you can reduce the amount of comment lines in your code. A code having a large amount of comments means that the codes are not readable enough.

Readable Code = Maintainable Code


Comments

For the latter example, I would prefer a combination of your method names:

  1. calculateSum()
  2. fillStudentList()

This would add a hint about the semantics of a method.

I've recently read the book Clean Code from Robert C. Martin: It builds up on these ideas and changed the way I thought about writing readable code.

kind regards
Bender.

I agree with your convention of using calculateSum() or fillStudentList().

For the article I wrote, i just used the method naming convention of java for getters and setters. That is using "get" at the beginning of a method name which retrieves or gets a value and "set" for methods which alters a value.

Clean Code from Robert Martin is nice! Cheers!

Add new comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • You may insert videos with [video:URL]
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd> <table> <tr> <td> <th> <img> <h1> <h2> <h3> <iframe> [video]
  • You can enable syntax highlighting of source code with the following tags: <code>, <blockcode>, <asp>, <c>, <cpp>, <csharp>, <css>, <html4strict>, <java>, <javascript>, <mysql>, <php>, <python>, <sql>, <vb>, <vbnet>. The supported tag styles are: <foo>, [foo].
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
CAPTCHA
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.