SA Developer .NET

Thought I'd like to get some feedback from the SADeveloper community on my latest little blog post:

Developers often talk of "self describing code". This term is a favorite answer when a developer's poor use of comments comes into question. Often the answer: "I don't need to write thorough comments, because my code is self describing." Ignoring the commenting part of the example, lets dwell further on the "self describing code" claim. So my question is how well does your code reveal it's purpose?

Let's take the following example into consideration. Let's say I need to determine whether data was binded to a control. The control has a property called Description, that will have a value after data was binded to it. So in order for me to determine whether the data binding operation completed successfully I could write the following code:

if ( string.IsNullOrEmpty( controlInstance.Description ) ) { ... }

So what does this say about the purpose of the code? Does this line of code clearly tell you that I am actually checking whether the control was data binded? No. That knowledge is hidden away, deep inside my head. Anyone looking at this line of code will immediately be confused as to why I am doing this check. So now I am faced with two choices; I can either put a comment next to the statement, or encapsulate the logic in a property or method that will reveal the meaning of the operation (preferably we should do both). The latter option will make the code self describing, and reveal it's intrinsic meaning:

/// <summary>
/// Checks if a data source was binded to the control.
/// </summary>
public bool DataBinded
{
    get
    {
        return !string.IsNullOrEmpty( this.Description );
    }
}

Our original line of code then becomes: if ( controlInstance.DataBinded ) { ... }

Looking at this code, there is no confusion at what I was trying to achieve. We now also have one place where we define what rules determine whether the control was data binded, so that if it needs to change, we only need to do it in one place.

The point is that there are a lot of things that need to be taken into consideration when writing and structuring source code, such as performance, coupling, inheritance hierarchy, abstraction, patterns and so forth. A very important one that I believe is too often neglected, or forgotten all together, is how well the source code communicates its meaning. In fact, personally I would say this aspect should be of the highest priority. I believe the team paying attention to this aspect of coding, will really reap the rewards once they have to start maintaining the product, especially as the original developers leave, and new ones join  the team. Considering that the maintenance of existing software can account for over 60% of all development effort, and that 70% of the cost of software is devoted to maintenance, I believe that any technique that can help with easing this task is of great importance, especially if it's something as simple as packaging and naming your code in a clear and concise manner!

Good structure, comments and sticking to standards is important. Developers don't always think about the person having to look after the code while developing or design a piece of software or code. I think code revision comes into play and giving that responsibility to maybe one or two senior level developers within a team. Using tools to check your code - like ReSharper - can also help. Code review should be an important part of the development cycle.

riaans:

Good structure, comments and sticking to standards is important. Developers don't always think about the person having to look after the code while developing or design a piece of software or code. I think code revision comes into play and giving that responsibility to maybe one or two senior level developers within a team. Using tools to check your code - like ReSharper - can also help. Code review should be an important part of the development cycle.

Hi RiaanS,

Couldn't agree with you any more! I have to maintain an app that has little to none comments, or any real coding standards. 2 pages that are from the same module, that do the same thing, are coded completely different from one another!

riaans:

Good structure, comments and sticking to standards is important. Developers don't always think about the person having to look after the code while developing or design a piece of software or code. I think code revision comes into play and giving that responsibility to maybe one or two senior level developers within a team. Using tools to check your code - like ReSharper - can also help. Code review should be an important part of the development cycle.

I think the point for me is more that developers should compose even small bits of logic into descriptive operations. In my example the developer could've added a comment next to the original comparison, but this would not universally retain its meaning, because we would still be duplicating the inherent rule across the application. Placing it inside a descriptive property, ensures that the meaning is clear wherever it's used. In other words, methods aren't just a place to put code, but should be named in such a way that it becomes self explaining.

I think that code should really read like a fluid interface (even if it's a property). Code reviews play an important role in this regard, but I have seen many senior developers not paying attention to this detail. The problem isn't originally apparent, but after a year or two of writing "if( ... ) else ( ... )" statements all over the place, it becomes a bigger and bigger pain for developers to maintain, understand, and even remember their code.It's a small detail, but one to watch out for.

Frequent updating of documentation and proper comments when checking code into source repository must be enforced to help with this process, else as mentioned, maintenance is painful on old code. And unfortunately we will never get away from maintenance.

riaans:

 

And unfortunately we will never get away from maintenance.

You got that right

Well, as a framework developer, my frameworks have to be easy for other developers to use, and my comments need to be IntelliSense friendly. Easier said than done:)

I think the biggest problem is that the developer-as-a-hobbiest still lives inside a lot of developers, and they're happy to keep fundamental aspects of the code locked inside their head. If you're not releasing your source to other developers (we DON'T let other developers, junior and senior alike, see the framework source - they must become flexible within it and not ask us to layer spaghetti code on top of it) you have to make the use of it as intuitive as possible. Besides, good source comments can lead to good documentation if you have a decent documentation generation engine.

Okay, let me ask the following questions:

1. When is it is appropriate to put conditional logic in a method/property? For instance do we do this if we use more than one conditional statement in an "if" statement? Do we do this when we use the conditional logic outside the current operation?

2. How do you know that you have given your method/property an appropriate name? Personally, I always run into the problem of having very long method names. Is this okay?

To give you an answer on maybe some of the questions:

1. I personally, NEVER put anything inside a property except basic get and set operations, that simply retrieve a value or set a value respectively. I put any type of logic into a method that I know will be re-used at least more than once in more than one location in my code. For example, for script injection checks, I placed the code to "encode" or "decode" the text inside a class called "Utils" that is placed in a Library Project, that I reference in every new project I use. If I need to make changes, or add new common methods, I simply extend the class (partial class) or create a new one that I inherit from. If I later discover I seem to be using the code more and more, I update my original base class to reflect the change.

2. I personally feel that longer names tend to be more descriptive, for example, in my common method library, I have a method called "GetValueFromWebConfig", which, as you can imagine, means that I use it to retrieve <appSettings></appSettings> values from my web.config file. It has all the relevant error handling code and checks to ensure the file is opened. This saves me from creating and disposing of the config object every time I need it. But to get back to the point, if I made the method name, for example, "GetValue", does that mean it performs conversion? Or retrieve a value from the database? The fully written name makes a lot more sense, especially if new developers to the company/group have to learn the company's practices.

Another alternative to long names is to make use of XML comments, and have a very nice, long and informative description about what the method does, including the purpose of the parameters, and the return type.

Just my 2c on the topic for the day.....

The H..................................................................

horatio:

2. I personally feel that longer names tend to be more descriptive, for example, in my common method library, I have a method called "GetValueFromWebConfig", which, as you can imagine, means that I use it to retrieve <appSettings></appSettings> values from my web.config file.

GetAppSettingFromWebDotConfig. 

ProfK:

horatio:

2. I personally feel that longer names tend to be more descriptive, for example, in my common method library, I have a method called "GetValueFromWebConfig", which, as you can imagine, means that I use it to retrieve <appSettings></appSettings> values from my web.config file.

GetAppSettingFromWebDotConfig. 

Ha ha ha. This is something that my previous senior dev would blow a gasket about if I didn't do it like you suggested!!!!!! Just to be a pain in the @ss!!!!