Question about style

For Beginners

Started by Bbalstrzmj90 August 18, 2004 11:52 AM

56 comments, last by JasonHise 19 years, 8 months ago

980

August 18, 2004 02:03 PM

Quote:Writing good code should be no harder than writing comments that explain what the code does. It's not very hard, honostly.

May I quote myself in response?

Quote:I would rather rename veriables and reorder functions and expressions in the time you would probably spend writing comments

Still it is a time-consuming job, and it is too easy to fall into hacking-mindstate and messing up one's design. At least, for myself, I find myself coding in 2 kinds of style:
1. slowly, carefully, adhering to object design and analysis, refactoring often, crawling, producing "da code"
2. live fast, die young, have a messy looking sourcecode

Thermo

bytecoder

100

August 18, 2004 02:11 PM

Quote:
May I quote myself in response?

Quote:
I would rather rename veriables and reorder functions and expressions in the time you would probably spend writing comments

I did notice that you said that before I posted, but I dismissed as a really big type or something :/

Quote:
Still it is a time-consuming job, and it is too easy to fall into hacking-mindstate and messing up one's design. At least, for myself, I find myself coding in 2 kinds of style:
1. slowly, carefully, adhering to object design and analysis, refactoring often, crawling, producing "da code"
2. live fast, die young, have a messy looking sourcecode

I don't find it very time consuming. If you already commented what it does, you should therefore know what it does, and how to make it more explicit. I remember once I coded a game without stopping once to compile it. Let's just say I didn't have fun the following 2 weeks when I had to debug it.

JohnBolton

1,373

August 18, 2004 02:47 PM

Quote:Original post by Terlenth
1. I am not a newb coder. I have been coding for approximately 5 years now mainly dealing with console programs but still doing fairly large works.

Ok, so maybe not quite a newb, but you haven't even finished college yet. I'm not trying to put you down, but you still have a lot to learn.

Quote:Original post by Terlenth
2. I have done a major project where myself and a friend of mine created a Java chat server. Similar to an MSN server. Didn't use comments.

You and one other person writing a chat server is not a major project.

Quote:Original post by Terlenth
3. The way that I use variable, function, etc labels is almost similar to writing comments.

That is respectable, but using well-named symbols is not sufficient except in trivial code. Again, how can code with well-named symbols possibly describe its purpose, its architecture, its limitations, and its assumptions?

John BoltonLocomotive Games (THQ)Current Project: Destroy All Humans (Wii). IN STORES NOW!

Terlenth

300

August 18, 2004 03:24 PM

I agree that I don't have all the experience in the world. I also understand that you probably don't hold College/University students in the highest regards when it comes to programming skills (normally because most of them feel that its the easy way through university cause they remember it as being the easy way out).

And, I also understand that you don't view the chat server as a major project, but to someone who is only 19 that is a pretty big accomplishment (especially since it was cross platform and would work with 2 clients 1 VB based and the other Java based).

As for my coding style, what I try to do is make my code as clear as possible. If I can't do that with my code labels then I will comment it. That's when it becomes necessary. I also realize that I will probably have to comment more when it comes to larger projects but again that is when my code become more complex and it requires the comments.

Edit: By the way John, by your definition then of a newb it probably makes the majority of the members of this site newbs if you mean that in order to graduate from newb status you have to be either graduated College or in College

--Ter'Lenth

Moolicious

130

August 18, 2004 04:03 PM

You should comment complex code. Try to read a huge project NOT programmed by yourself with no comments and see where you get. Your company will thank you. Do you honestly think that computer languages have been putting the feature of commenting in for no reason whatsoever? Commenting is NOT for NEWBIES, it's for complex code. PERIOD
What happens in the industry when some poor person has to edit/update/fix/patch your code? Don't you want to make their job easier by commenting? You can't pretent your code can be perfect always. What might seem obvious to you, may not be to others, and that's not because they are less intellegent. Please bear that in mind. Your lecturer might have a point. Commenting is good practice, if you expect others to be able to read your code efficiently and easily. No one wants to read every line of code to know what a function does.

P.S. Obviously don't over comment, not every line needs comments.

Terlenth

300

August 18, 2004 04:18 PM

I don't disagree with the fact that complex code needs to be commented and if the meaning of the code is not obvious then it should be also commented. For example:

Exerpt from one of my 1st semester Java assignments:

while (!eof)
{
//if the string line can't equal the file being read in the file isn't a proper format or doesn't exist
try
{
lineRead = ToRead.readLine ();
}
catch (Exception e)
{
System.err.println ("The first command line argument is incorrect please try a new argument");
System.exit (0);
}
if (lineRead == null)
eof = true;
else
{
//encoding lineRead so that it can be printed out
linePrint = encode (lineRead, shift);
ToPrint.println (linePrint);
}
}

Parts of this code aren't exactly easily understood. Therefore, they are commented. This being the main function of my program.

--Ter'Lenth

Moolicious

130

August 18, 2004 04:36 PM

Good work :)
That's what I like to see.
I'm happy now, you may continue.

bytecoder

100

August 18, 2004 05:11 PM

Quote:
Ok, so maybe not quite a newb, but you haven't even finished college yet. I'm not trying to put you down, but you still have a lot to learn.

Not that some of that isn't true, but seeing as how it doesn't look like you know the guy, I'm not sure why you would make such a statement. For example, I'm 14, and therefore obviously not in college, but for all you know I'm more skilled than most CS graduates.

Quote:
That is respectable, but using well-named symbols is not sufficient except in trivial code. Again, how can code with well-named symbols possibly describe its purpose, its architecture, its limitations, and its assumptions?

It can't. And that's when you should comment. Like I said before, having to comment what a piece of code does (as apposed to why it does it) is usually a sign of Code Smell.

Quote:
//if the string line can't equal the file being read in the file isn't a proper format or doesn't exist
try
{
lineRead = ToRead.readLine ();
}
catch (Exception e)
{
System.err.println ("The first command line argument is incorrect please try a new argument");
System.exit (0);
}

Not to burst your bubble or anything, but this comment could definitely be better. Infact, it's explaining what the code does, which is a big no-no.

Quote:
//encoding lineRead so that it can be printed out
linePrint = encode (lineRead, shift);
ToPrint.println (linePrint);

This is an unnecessary comment. It's already obvious that the following line 'encodes' 'lineRead.' However, renaming 'shift' to something more meaningful is probably a good idea.

[Edited by - bytecoder on August 18, 2004 6:11:24 PM]

Terlenth

300

August 18, 2004 05:32 PM

int shift possibly could be renamed to something like int char_shift. But, either way the variable name would have about the same amount of meaning.

I'm not exactly sure which comment you are refering to by it being a no-no but, so if you clarify I might be able to shed some light onto that one.

Again that was from 1st sememster during 1st year university. I went comment happy during 1st semester for the most part. I had the bad habit of adding comments afterwards.

Also, when it came to comments that was what the prof was teaching that semester and during that semester I played the "I want to get a good grade and pass this course" game.

--Ter'Lenth

Moolicious

130

August 18, 2004 05:49 PM

I'm looking beyond commenting a pong game. I didn't analize his code/comments, I just spotted that there were two which is good practice. University like any education wants you to employ good technique. You code how you practice. If you always write messy code, then you will always write messy code, weither it's a pong game or an operating system. Likewise with commenting, if you never practice it, chances are you will never do it. Commenting can save you time, later when you come back to old code. But if you don't want to believe me don't. Chances are it might not affect you, maybe you are never going to program in a team, so only you will read your own code.

I'd personally rather read commented code, when it's not my own code. So I would do it for others if they were forced to read my code. It saves time, and time is money in the workplace.

Question about style

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Question about style

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Reticulating splines