ImaginationOverflow

The knowings and experiences of a group of developers.

Self-Commented Code

“Self-Commented” code, that has to be the best expression I have ever heard regarding programmation.

I have to admit I’m not the best fan of comments, I kinda feel that when programming in java the javadoc infrastructure is useful and I try to do the best I can for my code but I don’t like to explain what a method does. Well today during class I smiled as I heard that expression and I love it now, to make code that one simply by reading knows exactly what it does, without further explanation, is just awesome.

Maybe you’re not seeing it, are you? Let me show a piece of “self-commented” code.


public class Condition extends Predicate<set>{ }

One can easily read that single line and understand what a Condition is:

– “The class Condition is a Predicate of Sets of Parameter.”

See? That was easy enough :).

Another good example would be.


new Command()
.withParameters(_paramA, _paramB)
.withConditions(new MandatoryParameters(_paramA));

So again it is easily readable, so let’s see:

– “I want a new Command with the parameters _paramA and _paramB that has a MandatoryParameter, _paramA.”

Who needs comments after that? Not only it is a work of art, it helps with understanding code for new people seeing it, as well as their own creators after some time. It also saves time when you need to fix something as you can easily identify what everything is doing, but there are still some situations where we can’t make such code so one should use comments to help understanding such code.

Note that while writting “self-commented” code is great to use internally if you want to export a jar in order for others to use, they won’t be able to read your code (unless you provide it) but javadoc is still a very useful tool for programmers. If you don’t know what javadoc is click here and start using it, if you do know but don’t use, because you’re lazy as I am or any other valid reason, I strongly suggest you start using.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: