how to make code more understandable?

Sun's standards are better than no standards but they're not perfect.

Of course the question of what comprises the best standards is a largely religious debate steeped in personal preferences and distastes, that's what makes it such fun to discuss things like the best bracing style :)

jwentinga at 2007-7-16 1:08:27 >

> What are three methods that can be used by a

> programmer to make code more easily understood by

> another program?

1. Hire well educated and smart programmers.

2. Hire well educated and smart programmers.

3. Hire well educated and smart programmers.

They know how to decompose a problem and use proper abstractions to make a program easy to understand and maintain.

..u..j....a at 2007-7-16 1:08:27 >

> > > > i think the question was to make the code

> > > > understandable by another PROGRAM

> > >

> > > That's probably a typo. How would other programs be

> > > able to understand your code?

> >

> > They do if they're compilers. -:)

>

> I really doubt that they understand the code :)

I'm planning to take an AI course. Hopefully I know the true meaning of "understand" after that.

..u..j....a at 2007-7-16 1:08:27 >

> some guy on this forum goes by the handle of

> Jschell.

> I've had discussion with him about coding standards.

> He won't want you to look at the coding standards

> published by Sun cause they are evidently evil so i

> won't advise you to look at them even though i think

> they are at least a place to start in lieu of using

> none.

>

> you should ask jschell for his version of coding

> standards.

If you're planning to take on jschell in a discussion you should ask me for advice on how to handle the JAP (jshell argumentation pattern -:)

Anyway I may agree with jschell on this. It's probably a good idea to let programmers put their beloved brackets where ever they want them. What I've found much more important for the readability of code is where you put stuff in class files. Programmers also are much more likely to accept such a standard.

This is the classfile layout I use. There is a certain logic to the order but the main advantage is that everybody uses it. You don't have to think about where to put stuff and you easily find stuff. It's simple and it really helps,

/* 1. Static variables */

/* 2. Variables */

/* 3. Static intializers */

/* 4. Enums */

/* 5. Static inner classes & interfaces */

/* 6. Static methods */

/* 7. Initializers */

/* 8. Constructors */

/* 9. Inner classes & interfaces */

/* 10.1 Methods - public */

/* 10.2 Methods - protected */

/* 10.3 Methods - default */

/* 10.4 Methods - private */

..u..j....a at 2007-7-16 1:08:27 >

> This is the classfile layout I use. There is a

> certain logic to the order but the main advantage is

> that everybody uses it.

>

> /* 10.1 Methods - public */

> /* 10.2 Methods - protected */

> /* 10.3 Methods - default */

> /* 10.4 Methods - private */

Don't you find the following easier to read?

public class Example {

public void example() {

_example()

}

private void _example() {

...

}

public void example2() {

...

}

public void example3() {

...

}

}

versus

public class Example {

public void example() {

_example()

}

public void example2() {

...

}

public void example3() {

...

}

private void _example() {

...

}

}

Personally I find it useful to put my private methods after the public method that uses them.

_bensmytha at 2007-7-16 1:08:27 >

> I always group my methods logically. I don't care

> about their visibility.

The problem is that "putting things logically" requires thinking as to where to put stuff and that's what you want to eliminate. What you find logical may be totally illogical to everybody else. It may be even to yourself after a while.

In my experience a totally automatic layout is wastly superiour to one based on everybody's idea of what's "logical" and "natural".

..u..j....a at 2007-7-20 18:28:07 >

> > In my experience a totally automatic layout is wastly

> > superiour to one based on everybody's idea of what's

> > "logical" and "natural".

>

> But why would it be any better than just putting it

> where you logically think it fits?

It's because everybody's logical order is different from everybody else's and sometimes even your own after a while -:).

> Most programmers (in large projects) use an IDE, and

> most IDEs are capable of incremental search and to

> jump to a highlighted method. They do also have a

> tree browser which shows the outline of the class

> (and that browser do often show the methods in

> alphabetical order)

Regardless of IDE, in my experience in large projects a substantial amount of time is spent to find stuff. And, maybe even more importantly, in figuring out where to "logically" put stuff.

I've found that taking the "logic" out of the class layout really is as a great relief. It has a much bigger positive impact than for example standardizing on a coding style such as K&R, which also tends to seriously annoy those programmers who had to give up their favourite style.

I've also standardized commenting but I better not mention it. -:)

..u..j....a at 2007-7-20 18:28:07 >

> Regardless of IDE, in my experience in large

> projects a substantial amount of time is spent to

> find stuff. And, maybe even more importantly, in

> figuring out where to "logically" put stuff.

I don't think I spend much time finding stuff. I just type ctrl+shift+t (open type in eclipse). Type the class name, press enter. Then type ctrl+j (incremental find) and start typing the method name. I would do the same thing even if you have placed the methods by visibility. Btw. Grouping by visibility makes refactoring harder, and who remembers if a certain method is public or not? I think you spend as much time navigating the files as I do.

Kaj

kajbja at 2007-7-20 18:28:08 >

> Programmers generally don't like to comment because

> they feel it's in the code anyway so I've

> standardized on three method comments that appear

> before any method definition.

>

> // Requires: constraints on use

> // Modifies: modified input

> // Effects: the behaviour

I use preconditions, post-conditions and invariants because I'm a fan of 'design by contract'.

sabre150a at 2007-7-20 18:28:08 >

> 2. Lots of comments.

That depends on what kind of comments you write.

> Comment [...] any section of code that appears difficult

> to follow.

Another approach would be to refactor the code, i.e. create smaller methods with names that explains what is going on.

> It is better to have too many comments

> than not enough.

Again, that depends on what kind of comments you write. Too many inane comments clutters up your code and makes it difficult to follow.

> I never did understand the

> problem with not putting in too many comments, the

> compiler will get rid of them anyway.

The main point of writing comments is to make the code easier to understand for humans. The compiler has nothing to do with it. Too many comments clutter up the code.

The goal, of course, is to write code that doesn't need any comments at all.

happy_hippoa at 2007-7-20 18:28:12 >

>

> > The goal, of course, is to write code that doesn't

> > need any comments at all.

>

> I would recommend javadoc comments for all publicly

> exposed API, though...

That's true. I was talking more about // comments, but good point.

happy_hippoa at 2007-7-20 18:28:12 >

> I would rather have too many comments and be sure that

> my code can be maintained in the future than have

> some code that is forgotten one day because no one

> can fix it.

I would rather have well-factored code with meaningful method and class names. I find comments to be largely untrustworthy; they tend not be changed as often as the code is, and having "too many" just exacerbates the problem. If the code needs commenting, it needs refactoring first.

yawmarka at 2007-7-20 18:28:12 >

> This is the real world

I believe you're under the mistaken assumption that I work somewhere other than in "the real world".

> it is probably impossible to achieve

I don't hold quite as negative perspective as you seem to, and I don't share the same experience.

yawmarka at 2007-7-20 18:28:12 >

> 2. Lots of comments. Comment each class file, each

> method and any section of code that appears difficult

> to follow. It is better to have too many comments

> than not enough. Make sure you explain what the

> class is should do and what it will not do and the

> same for the methods. I never did understand the

> problem with not putting in too many comments, the

> compiler will get rid of them anyway.

Example of too many comments:private String playerName; //name of player

private float playerHealth; //health of player

...

public void setplayerName( String name ) //method to set the player name

{

playerName = name; // store the player name

} //end method setplayerName

@Michael - I apologise for using your code as an example. But I think [url=http://forums.java.sun.com/thread.jspa?threadID=682116&messageID=3975095#3975095]my comments[/url] should explain why.

_bensmytha at 2007-7-20 18:28:12 >

> Sorry, I guess we have been at extreme ends of the

> programming world. I have had to rip apart legacy

> code that even when the comments were wrong they at

> least provided a clue as to where the code was going.

> They were a life saver. You assume that everyone

The reverse is far more common, in which the comment will completely throw you off the scent.

If the comment is written in a different language from your own it gets even more interesting (like the time we were working with a Dutch/British team and ran into some legacy code that had all variable names as well as all comments in Danish, of course no other documentation existed).

> e can re-factor the code to perfection until no

> comments are needed. My experience is that the

> majority of programmers do no write good code and you

> are stuck with what you get. I would prefer first

If they don't write good code they won't write good comments either.

Writing good comments is even harder than writing good code.

> the programmers add as many comments as they feel is

> necessary. This is the real world and if you start

But no more than necessary, and if more than a bit of commenting is needed the code should probably be rewritten to be more readable on its own.

> telling newbies to put in no comments you are going

> to get exactly what you asked for, code that no one

> can fix.

You'll get that anyway :)

jwentinga at 2007-7-20 18:28:17 >

Sorry, still can't agree. I will agree that comments should be kept to a reasonable amount such as not a comment for every line of code. But it doesn't matter if the comment is wrong or right. If you are a talented programmer you will recognize based on the code what is right and what is wrong. If code was always so easy to follow why hire big expensive teams to re-write the code. Because as I said in the first place most programmers doe not write good code and that is not likely to change in the near future.

Any help I can get in code I consider a bonus. As for any other type of documentation if they don't write or maintain good comments they probably are not going to write or maintain any good documentation so we go back to the only solution throw out all the comments, documentation etc and only have pure code that everyone can read because we all right perfect code right.

MexicoClivea at 2007-7-20 18:28:17 >

> > The reverse is far more common, in which the

> comment

> > will completely throw you off the scent.

> > If the comment is written in a different language

> > from your own it gets even more interesting (like

> the

> > time we were working with a Dutch/British

> team and

> > ran into some legacy code that had all variable

> names

> > as well as all comments in Danish, of course

> no other

> > documentation existed).

>

> Who tought them Danish? :)

We requested (and got) budget for a Danish-English dictionary.

jwentinga at 2007-7-20 18:28:17 >

> gnu source code to figure out the problem and without

> the arcane comments which are hard to follow I would

> not have had the compiler available to do the project

> and would have been in some serious dodo. Those

> comments literally save my job. So as far as I am

> concerned people put in all the comments you want one

> way or another we will figure out the good ones from

> the bad ones. (just not one on every line).

// add 1 and 1 to get the result

int result = 1 - 1;

This is maybe too obvious but many faulty comments exist that can seriously throw you off your mark.

I've seen code where the comments said one thing and the code did something completely different.

The code was not buggy (it had changed functionality over time causing something else to fail years later), if it had worked as the comments said it would it would have worked fine.

When originally written that code was just fine and followed the comments.

Then code was written depending on that other code, after which the code had been changed but the comments (which were now meaningless) were left in place.

The code was such a mess that we spent days looking for the problem, initially just believing the comments to be correct (why would they be there otherwise?).

Only when we went through the code line by line did we figure out it did NOT do what the comments suggested. Had those comments not been there we'd have done that immediately and saved ourselves at least some 10 man hours of work (and likely more).

So BAD comments are worse than no comments, and a LOT of comments are bad comments.

Even more comments turn bad as the code they are commenting is changed or removed without the maintenance programmer bothering to change the comments to match.

I agree that GOOD, well maintained comments, are a boon. But those are in the minority.

jwentinga at 2007-7-20 18:28:17 >

> I agree that GOOD, well maintained comments, are a

> boon. But those are in the minority.

The comments I have in the inherited code are no less than a horror. I had to update all the comments to make my life easier. One that I recently noticed...

// If the first character is 'G', return true.

if(key.charAt(1) == 'G') return true;

I usually find it better to ignore some of the code comments. They often tend to confuse me.

annie79a at 2007-7-20 18:28:17 >

> The comments I have in the inherited code are no less

> than a horror. I had to update all the comments to

> make my life easier. One that I recently noticed...

>

> // If the first character is 'G', return true.

> if(key.charAt(1) == 'G') return true;

Yep, mark another one up for the "Bad" column... :o)

yawmarka at 2007-7-20 18:28:17 >

> The basic question that I believe we are all running around is

> do programmers in general write good code.

Rather, I think the fundamental difference is simply point-of-view. We all seem to agree that the ultimate goal is whatever meets our interpretation of "good code", and that this type of code has minimal, pertinent comments and is well-documented. We just seem to disagree on how to get there.

You seem to look that "the way things are", and see that the solution is for programmers to write copious comments - for good or ill - because most programmers suck and the more comments they write, the better chance you as a maintainer have of figuring out what was going through their brain when they wrote the mess they did.

I don't completely disagree with that. Some tidbit buried in a sea of bad comments just might provide you with some insight you wouldn't have found otherwise.

However, I would prefer coaching and collaboration, review and critique, and a healthy emphasis on refactoring for maintainability/continuous improvement as opposed to a culture of "just throw more comments in there". Copious, superfluous comments tend to obscure the problem rather than clarify it. Programmers that are in the habit of obscuring problems should be coached out of that habit.

As said, we seem to agree on where we like to be; we just seem to differ on our how to get there and our likelihood of doing so. For the most part, however, my responses are simply inspired by your talent for hyperbole... :o)

> All programmers believe they write good code.

I'm well aware of my shortcomings. Some of the stuff I write, I'm proud of. Other stuff, I think is the pants. That's why I continue to study, practice, and refactor: to get better.

yawmarka at 2007-7-20 18:28:21 >

> You keep saying that the best thing is to write good

> code but where are all these projects coming from

> that have bad comments and require a serious amount

> of work to fix. A lot are coming from people that

> don't write good code in particular or just don't

> maintain it. So at the end of the day I will still

> take all the bad and good comments I can get and hope

> I can make some sense out of it.

But that requires that you read the code to see if the comment is correct or not, so why not just read the code and skip the comment?

I agree with those who think that comments should be used to comment the public contract of a class, but a comment should not reveal implementation issues.

Kaj

kajbja at 2007-7-20 18:28:21 >

> > All programmers believe they write good

> code.

>

> I'm well aware of my shortcomings. Some of the stuff

> I write, I'm proud of. Other stuff, I think is the

> pants. That's why I continue to study, practice, and

> refactor: to get better.

That's a plus for you. :)

Every time I look at my old code, I always find something which could have been done in an easier way. Unfortunately, I don't get to change it that often. :p

annie79a at 2007-7-20 18:28:22 >

> Why have any javadocs at all. Just publish the

> source code and everyone will immediately know how it

> works and what it does.

I do NOT want to read source code to figure out what something does.

When I use the JDK I use javadocs to research and orchestrate which classes and methods to use. I sure don't want to read source code to do it. No one should have to read my source code to know what objects I've written do, either.

(Hope this wasn't sorted out later in this thread.)

(Hope I don't look like one of those super-serious, self-important programmers that MexicoClive bonks later in the thread.)

%

duffymoa at 2007-7-20 18:28:22 >

> @annie, keep up the good work moderating the animals

> on these forums. Without some of your comments I

> swear some of the people would start reaching right

> through the screen and kill each other.

I take it as a compliment. Thanks! :)

I don't think overly serious programmers would not be serious enough not to reach for their boss and strangle him/her rather than reaching through the screen. Some of the serious remarks are better when poured out in words rather than keeping them boiling inside. There's a lot of chaos in the life of good programmers.

annie79a at 2007-7-20 18:28:22 >

> 1. Use lots of comments.

i disagree with this..i only use comment where necessary...where the

code would be hard to understand if there were no comment..mostly, i

only have Javadoc most of the time

> 2. If in a corporate environment, develop a written set of standards &

> enforce them.

although i don't like to be force to a standard..it does make life much easier. It's hard to switch looking t one style..another style..and another..back and forth

> 3. If using an IDE that supports it, configure it to automatically format

> your code to the accepted standard.

yes..but a pain when your project is in a CVS, etc..when it come time to merge..and you have to look at the differences (such as a space..urgh)

> 4. Peer reviews.

huh? your peer would have a set of standard that they prefer..and wuold suggest you to follows their.

I say..in a oporate..they need to adopt one standard and everyone must follow..a code review one a while would enforce to make sure the standard has been followed. This would mean one uniform standard..easier to maintain, etc..

just hope the standard does not include hungarian notation (cept for gui component...which i don't mind..cause it make it more clear what component type it is)..but no iList for interface List, strName for a String

only other time i don't mind hungarian notation is something like

String strItemId = request.getParameter("id");

if (strItemId.indexOf("9") != -1 && strItemId.indexOf("5") == 2)

...

else

...

Long itemId = new Long(itemId);

tnguyen1973a at 2007-7-20 18:28:26 >

My Two cents worth...

I've been a programmer in the past, and never commented anything. That's not a comment on the good or bad, just a statement of "history" if you will.

A couple of months ago I started learning OOP using Java at uni. My first simple assignments (one or two class files) had comments up the wazoo. Later, as I started writing stuff for my own edification, I fast realized that all these comments made the code really hard to read. So I started dropping comments from simple things.

I started writing multi-line comments in the body of my code to explain what I was trying to achieve in the following lines. Understand, this was largely just for me; it was my reminder of what I needed to do, with what variables/objects, etc. I consider these "construction underway" comments, and I've started removing them once the block of code works because, once again, I found it hard to read through a method so spaced out by comments.

I was also writing multi-liners at the start of methods to explain what the method was supposed to do - again, largely notes to myself to remind me what I had to achieve with the method. I started taking these out too as I found I had to change what the method did in a substantial way.

Of course, as stated, I'm a noob. I'm not stupid, but I'm inexperienced with OO in general and Java in particular, so often I have no idea how to tackle a problem before I start, therefore my code can (and usually does) change drastically from inception to completion.

As also stated, I'm using comments as a kind of very basic design system; it's my way of thinking through how I (might) write some code, and putting those thoughts in words so I have a reference while I attempt to write the code. But mostly I remove these things once the code is working.

All of that leads me to this: I have discovered, even at my early stage of learning, that once I've figured out how to do a specific task or group of tasks, I can look at the code and see what it does. If a method starts to get long, or perhaps has some particularly "busy" block of code, I'll write a new method with a mnemonic name, and tranfer that code to it.

Personally, I find that far, far more understandable than MY OWN COMMENTS ever where!

My status quo is that I'll use comments in very rare cases (once I'm finished writing that code) for things such as a control loop with long lines that mess up the visual layout and can make it difficult to "see" the flow. Example, I might end a loop with:} // end loop i

as a visual que. The lovely green text makes it very easy to quickly see where the loop ends.

As I progress into more complex programs, I am forming the opinion that EXTERNAL documentation would be the smart choice. Even with the short programs I've written so far, comments (with rare exceptions) make reading the code more difficult, and reading the code is a better means of understanding what it does than comments.

And before someone writes this off as a trivial example, not pertinent to major software development scenarios... You know what? If that is the environment then you SHOULD have up-to-date User Requirements with use-case statements linked to some UML modelling tool. THERE is the best documentation you can have for your business-related comments. The UML model is your best description of the application, and the User Manual is the best documentation on how to use the program. The code itself is its own description of how the program achieves finer details; if it's badly written, it needs to be REwritten... putting all the comments in the world in the code won't change that simple fact.

Someone in this thread said something about writing good comments is harder than writing good code. I agree. The compiler, and then the behaviour of your code as you test it, will enforce at least some constraints on how you write code, but there is nothing but the programmer's own literary skills to "enforce" good comments, and then they may not be accurate. In my assignments at uni (an online uni), I read a lot of submissions from folk who have presumably completed High School and at least 2 years of college; but they can't construct a sentence! The degree I'm doing is software engineering; presumably at least some of these folk are going to be programmers, at least for a while. I shudder to think what the comments will look like.

I'd rather not have to fix code (one day) written by one of these people, but I sure as heck don't want to try to make heads or tails out of the stuff they call English within their comments.

My Vote: Comment if you really must, but keep it to the absolute barest minimum. If your code isn't readable, then you REALLY need to work on THAT, not use comments like some kind of bandaid.

'Nuff said.

ConanOfOza at 2007-7-20 18:28:26 >

> jwenting said:

> I agree that GOOD, well maintained comments, are a

> boon.

>

> How you make a leap from that to "don't put in

> comments and forget the documentation", I don't know.

> Maybe it's that dearth of common sense to which you

> refer...

I don't say don't comment, I say don't go overboard and certainly don't comment things because your code sucks and comments are the only way to make it understandable (fix the code instead).

jwentinga at 2007-7-20 18:28:26 >

I I've found these three comments very useful at the beginning of a method.

// Requires: (constraints on use)

// Modifies: (modified input)

// Effects: (the behaviour)

The emphasis in on explaining what is done rather than how. The detailed how is best explained by the code itself enhanced with very sparse "hints".

..u..j....a at 2007-7-20 18:28:26 >

> >

> > If he can distinguish between the two easily then

> > what is the problem. Let the programmers put any

> > comments they want and at the end of the day a

> good

> > programmer will know the difference. You can't

> have

> > it both ways. You say bad comments make ti

> difficult

> > because you follow them and they make your life

> > difficult and then say you can distinguish between

> > them easily.

> >

> Bad comments cost time, non-maintained comments can

> be fatal.

> Bad and incorrect comments should be treated like

> bugs in the code in the same way bad or incorrect

> code is.

> Superfluous comments should be refactored out just

> like superfluous code.

>

> > I still prefer funny comments. Would anybody care

> to

> > add some funny comments to this conversation.

>

> Sure, funny comments make your day. A bit of humour

> never hurts if it's to the point.

Sorry Mr jwenting. Just pulling your leg a little, I agree with all this that minimal comments are the best it's just that a lot of programmers that I have met should put in a lot of comments or noone will understand the code. But as previoiusly mentioned they all believe they are good programmers. I believe I said every programmer should put in comments as he/she feels is necessary. If that means very few then go for it

As for pointy jokes

Q. If Mr. Spock has pointed ears, what does Mr. Scott have?

A. Engineers.

Sorry best I could do in short notice and yes it is recycled material. Anyone else have pointy jokes.

MexicoClivea at 2007-7-20 18:28:26 >