What makes code good?
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
It compiles :-D Seriously, I would generalize your first point to the "Principle of Least Surprise", and then fully agree with you, in the given order. 1) I see POLS as the goal/idea, and consistency as the means to reach that. i.e. consistency with surrounding code, with team style guidelines, with "how it's always been done", with "how everyone else does it", with "the first idea you have to do it". There is of course a lot of room for arguments here, that's why the containing principle is necessary. I wonder if there are other measn than consistency? 2, 3) ideally, the code clearly states HOW something is done, and the comments tell you WHY. That's not always attainable, but a good goal 4) Here I'd add Methods/Classes/Components wiht a precicely defined job, and an interface contract that is simpler than the implementation. (Contract including the necessary documentation)
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighist -
Josh Smith wrote:
- Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented.
I tend to comment long sections of code at the beginning and describe the general process that block is executing. Even if what that code does is fairly straightforward, I can't count how many times I've gone back, read my own comment, re-read the code, and realized I screwed some part of that process up. It also seems to help coworkers who pick up my stuff to work on it - I almost never get questions about how my stuff works.
Josh Smith wrote:
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code?
I think you've covered the big ones.. ones I would add are: 1) Keep the amount of hackery to a minimum. Very rarely does being clever actually gain you anything and it only serves to obfuscate your code. 2) As a corollary to 1), Know your libraries. 2b) USE YOUR LIBRARIES. I cannot count the number of times I have picked up someone else's code and find that they've re-written half of what the String object in C# can do using methods obviously ripped from 32-year-old c-code. Knowing your frameworks and libraries is as important as knowing how to architect a piece of software. The less code you write, and the more work your time-tested libraries do, the fewer bugs you're going to have. Guess that's all for now..
Patrick Sears wrote:
1), Know your libraries. 2b) USE YOUR LIBRARIES.
Great point.
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
It's simple, really: If I write it, it's good. If you write it, it's probably a bug infested piece of binary twaddle worthy of only temporary residence in the Recycle Bin! On a more serious note, consistency and thoughtful, *logical* naming make a huge difference, as well as a clean design. I've always thought that the pascal code that came with Borland's VCL was some of the cleanest code I've ever seen.
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
-
It's simple, really: If I write it, it's good. If you write it, it's probably a bug infested piece of binary twaddle worthy of only temporary residence in the Recycle Bin! On a more serious note, consistency and thoughtful, *logical* naming make a huge difference, as well as a clean design. I've always thought that the pascal code that came with Borland's VCL was some of the cleanest code I've ever seen.
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
Jim Crafton wrote:
If I write it, it's good.
You must have difficultly getting into buildings, considering that your ego is too big to fit through a door! ;P
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Josh Smith wrote:
Too many comments make it difficult to read the code, too few comments force you to read code
This is true of all parts that you listed. Consistency is nice, but when consistant naming conventions use: int Volume_of_Fuel_for_Onboard_Motor_Sensor_of_Aircraft_Taco_Wing_from_Hanger15=0; too much of anything is a bad thing. Too much emphasis on design and future upgradeability, with little emphasis on functionality is bad, so can the reverse. Too much detail, or not enough detail in variables or comments each will be a bad thing. So my theory on good code can be broken down into one word: Balance. Get the point across, be succinct, not wordy, but be accurate and very clear about what is what. Comments, or code. Styles should be rapidly readable to much elegance can crowd the screen (I have heard requests for 4 spaces before and after {} which means 8 spaces for every open/close). Too much freedom of saying, "they just buy bigger hardware if it isn't fast enough" or too much focus on squeezing the last cpu cycle out of a CISC turnip processor. Too much of anything can be bad. well, except pay, they are welcome to pay me more to test that theory anytime.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Currently, I am reading this book: Beautiful Code[^]. I must say that content wise it is one of the best books I have read. I will rank it high up with books: Code Complete, Design Patterns and Refactoring.
Josh Smith wrote:
Thoughtful naming
Agreed! To me intent code should be just be obvious by reading it. If the code adheres to well known patterns things are a lot easier.
Josh Smith wrote:
I think that all non-private members of a type should be commented
The tricky parts always should have comments. But I hate comment clutter. I personally hate XML comments (javadoc is a little better) and I wish if there was an alternative. When you publish an API all public members should be documented but I necessarily don't agree that they should have comments on top of them. For example, I hate comments likes these if they appear everywhere and just convey the obvious. However, for something not very obvious things have to be commented.
public class Employee
{
///
/// Gets or sets the employee name
///
public string Name
{
get {return this.name; }
set { this.name = value; }
}///
/// Call this method to increase the salary of the employee
///
public void IncreaseSalary(double salary)
{
....
}}
Another thing issue I have seen is sometimes you may use a well known design pattern and the meaning may not be obvious to some programmers but programmers who have read the design patterns book may immediately recognize the pattern and understand how the code works. In such a case I think I will prefer programmer education rather than cluttering the code.
Co-Author ASP.NET AJAX in Action
-
Josh Smith wrote:
- Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented.
I tend to comment long sections of code at the beginning and describe the general process that block is executing. Even if what that code does is fairly straightforward, I can't count how many times I've gone back, read my own comment, re-read the code, and realized I screwed some part of that process up. It also seems to help coworkers who pick up my stuff to work on it - I almost never get questions about how my stuff works.
Josh Smith wrote:
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code?
I think you've covered the big ones.. ones I would add are: 1) Keep the amount of hackery to a minimum. Very rarely does being clever actually gain you anything and it only serves to obfuscate your code. 2) As a corollary to 1), Know your libraries. 2b) USE YOUR LIBRARIES. I cannot count the number of times I have picked up someone else's code and find that they've re-written half of what the String object in C# can do using methods obviously ripped from 32-year-old c-code. Knowing your frameworks and libraries is as important as knowing how to architect a piece of software. The less code you write, and the more work your time-tested libraries do, the fewer bugs you're going to have. Guess that's all for now..
Patrick Sears wrote:
Know your libraries.
Very important point! I missed that in my reply. I think the biggest change in my life as a developer (15 years now? :omg:!) is the heavy shift from "environment + my code" to "environment + layer 1 + layer 2 + ... + layer N + library 1 + ... + library N + my code".
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighist -
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Damn, I must be a lousy programmer. 1)I never pay attention to consistency, becuase I always change my mind. Sometimes In my one page I don't even have the same prefix on the same type of object. 2)I never think much about a name because you can always rename somthing in Visual Studio (even if it does take a while for the program to update all the references) 3) I usually go back and add comments after I'm done just in case I have to update the app in the future. I doubt they are smart though. I always thought what made code good was 1:Efficiency - Meaning the code will scale for a lot of users (web based) and not hog resources (windows based) 2:Conciseness - Not writing 100 lines of code when you only need 10 3:Simplicity - No need to reinvent the wheel. I have seen some smart programmers write stuff that is really complicated just because they enjoy the challenge. 4: Good Class / Database Design - Most apps succede or fail based on the design of your database tables and or class objects.
I didn't get any requirements for the signature
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
#1. Maintainability #2. Reusability #3. Extensibility
Best wishes, Hans
[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
A good design goes a long way toward making good code. The rest is just style, common sense, and coding rules. [edit] And if you continue the analogy, a good set of requirements makes for good design, and a good set of requirements comes from a good relationship with the client. Therefore, good code starts with a good client. [edit] Marc
-
Currently, I am reading this book: Beautiful Code[^]. I must say that content wise it is one of the best books I have read. I will rank it high up with books: Code Complete, Design Patterns and Refactoring.
Josh Smith wrote:
Thoughtful naming
Agreed! To me intent code should be just be obvious by reading it. If the code adheres to well known patterns things are a lot easier.
Josh Smith wrote:
I think that all non-private members of a type should be commented
The tricky parts always should have comments. But I hate comment clutter. I personally hate XML comments (javadoc is a little better) and I wish if there was an alternative. When you publish an API all public members should be documented but I necessarily don't agree that they should have comments on top of them. For example, I hate comments likes these if they appear everywhere and just convey the obvious. However, for something not very obvious things have to be commented.
public class Employee
{
///
/// Gets or sets the employee name
///
public string Name
{
get {return this.name; }
set { this.name = value; }
}///
/// Call this method to increase the salary of the employee
///
public void IncreaseSalary(double salary)
{
....
}}
Another thing issue I have seen is sometimes you may use a well known design pattern and the meaning may not be obvious to some programmers but programmers who have read the design patterns book may immediately recognize the pattern and understand how the code works. In such a case I think I will prefer programmer education rather than cluttering the code.
Co-Author ASP.NET AJAX in Action
Rama Krishna Vavilala wrote:
I personally hate XML comments
I can recommend this. http://visualstudiohacks.com/CRDocumentor[^] It's dynamic as well, so updates the display as you type.
Kevin
-
A good design goes a long way toward making good code. The rest is just style, common sense, and coding rules. [edit] And if you continue the analogy, a good set of requirements makes for good design, and a good set of requirements comes from a good relationship with the client. Therefore, good code starts with a good client. [edit] Marc
Marc Clifton wrote:
The rest is just style, common sense, and coding rules.
You know what they say about common sense, right... :)
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
It compiles :-D Seriously, I would generalize your first point to the "Principle of Least Surprise", and then fully agree with you, in the given order. 1) I see POLS as the goal/idea, and consistency as the means to reach that. i.e. consistency with surrounding code, with team style guidelines, with "how it's always been done", with "how everyone else does it", with "the first idea you have to do it". There is of course a lot of room for arguments here, that's why the containing principle is necessary. I wonder if there are other measn than consistency? 2, 3) ideally, the code clearly states HOW something is done, and the comments tell you WHY. That's not always attainable, but a good goal 4) Here I'd add Methods/Classes/Components wiht a precicely defined job, and an interface contract that is simpler than the implementation. (Contract including the necessary documentation)
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighistpeterchen wrote:
ideally, the code clearly states HOW something is done, and the comments tell you WHY.
The last bit is the biggest failing in commenting.
Kevin
-
Jim Crafton wrote:
If I write it, it's good.
You must have difficultly getting into buildings, considering that your ego is too big to fit through a door! ;P
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Not at all - I simply use my amazing mentat training and adjust the building's geometry at the quantum level to suit my needs.
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
-
Josh Smith wrote:
Too many comments make it difficult to read the code, too few comments force you to read code
This is true of all parts that you listed. Consistency is nice, but when consistant naming conventions use: int Volume_of_Fuel_for_Onboard_Motor_Sensor_of_Aircraft_Taco_Wing_from_Hanger15=0; too much of anything is a bad thing. Too much emphasis on design and future upgradeability, with little emphasis on functionality is bad, so can the reverse. Too much detail, or not enough detail in variables or comments each will be a bad thing. So my theory on good code can be broken down into one word: Balance. Get the point across, be succinct, not wordy, but be accurate and very clear about what is what. Comments, or code. Styles should be rapidly readable to much elegance can crowd the screen (I have heard requests for 4 spaces before and after {} which means 8 spaces for every open/close). Too much freedom of saying, "they just buy bigger hardware if it isn't fast enough" or too much focus on squeezing the last cpu cycle out of a CISC turnip processor. Too much of anything can be bad. well, except pay, they are welcome to pay me more to test that theory anytime.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
El Corazon wrote:
Balance.
Wish there was a way to vote that a 10 - in all things, Balance! :)
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Good code is that which you don't mind looking through when you are tired/hungover/grumpy - i.e. easily read and understood.
'--8<------------------------ Ex Datis: Duncan Jones Merrion Computing Ltd
-
Not at all - I simply use my amazing mentat training and adjust the building's geometry at the quantum level to suit my needs.
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
Jim Crafton wrote:
I simply use my amazing mentat training
Perhaps you need some more "mentat" training Your Majesty. :laugh:
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
Jim Crafton wrote:
If I write it, it's good.
You must have difficultly getting into buildings, considering that your ego is too big to fit through a door! ;P
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Keep it simple. Some programmers like to write a hundred lines of code because it makes them feel like a programmer. Fuck that, write it in 20 because YOU ARE a programmer. Write everything out on paper before you even touch the keyboard...think it through. Take your time. Haste does make waste...and stinky waste it is.
[ Don't do today what can be done tomorrow!! ;) ]
-
Josh Smith wrote:
You must have difficultly getting into buildings, considering that your ego is too big to fit through a door!
And his ass.
INITCOMMONCONTROLSEX wrote:
And his ass.
Speaking of asses...
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.