What makes code good?
-
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:
But I hate comment clutter.
I agree. Years ago in a previous career, I worked with a wise, old man who taught me what has become a valuable lesson: It is better to smoke no cigar than a bad cigar. I have adapted this to many different situations. It is better to write no comment than a bad comment. Like your examples of comments that add no value to the code.
Rama Krishna Vavilala wrote:
In such a case I think I will prefer programmer education rather than cluttering the code.
Agree with this, also. It might be nice to include a reference to the book in case like this. BDF
-
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:
int Volume_of_Fuel_for_Onboard_Motor_Sensor_of_Aircraft_Taco_Wing_from_Hanger15=0;
Hey its an aircraft... you might think about copy and pasting that name a few times to make sure its redendent enough not to make a mistake :)
-
El Corazon wrote:
int Volume_of_Fuel_for_Onboard_Motor_Sensor_of_Aircraft_Taco_Wing_from_Hanger15=0;
Hey its an aircraft... you might think about copy and pasting that name a few times to make sure its redendent enough not to make a mistake :)
StevenWalsh wrote:
you might think about copy and pasting that name a few times to make sure its redendent enough not to make a mistake
naw, just copy and paste the entire routine for filling one tank into another routine to fill the other tank, or better yet, copy and past the whole thing into main!
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Hey now! Watch that tone - let's have some proper respect here! :)
¡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
Ego sum rex VCF et super grammaticam ;) (that is, you are the king of VCF, and are above grammar)
Tech, life, family, faith: Give me a visit. I'm currently blogging about: Minnesota Bridge Collapses The apostle Paul, modernly speaking: Epistles of Paul Judah Himango
-
Ego sum rex VCF et super grammaticam ;) (that is, you are the king of VCF, and are above grammar)
Tech, life, family, faith: Give me a visit. I'm currently blogging about: Minnesota Bridge Collapses The apostle Paul, modernly speaking: Epistles of Paul Judah Himango
Bah humbug! Grammar schmammar! Next yu'll kumplane abowt my speling!
¡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.
Being the most expensive aspect of business software development it is also the most overlooked, instead "get it done"-itis sets in and it all rolls down hill from there. For consistency, I think the most important level of consistency is developer level consistency and not team level consistency. 1) Because it is easier to obtain and 2) because in all my years I have never seen a team, who requires team level consistencies, actually be consistent were it counts. On commenting, which is crucial, if your comments match the type of comments a machine generator for comments produce then you are not actually commenting code. Corollary to this is that automatic commenting systems do not generate comments. Thoughtful naming, if more developer learned to type the world would be a better place. Solid foundation in basic computer science principles and a complete understanding of basic programming concepts. Heh, I could go on but I shouldn't.
File Not Found
-
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:
Currently, I am reading this book: Beautiful Code[^].
I hate you! i was trying to save money :(
-
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.
Completely altering the functionality of an application with just 1 line of code :rolleyes: just kidding;P
**
xacc.ide-0.2.0.77 - now with C# 3.5 support and Navigation Bar!^
New xacc.ide release RSS feed^**
-
Completely altering the functionality of an application with just 1 line of code :rolleyes: just kidding;P
**
xacc.ide-0.2.0.77 - now with C# 3.5 support and Navigation Bar!^
New xacc.ide release RSS feed^**
leppie wrote:
Completely altering the functionality of an application with just 1 line of code
I can do that with most any program by inserting "=0" into the appropriate line. :) zero does amazing things to functionality. :)
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
INITCOMMONCONTROLSEX wrote:
And his ass.
Speaking of asses...
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Aw, give 'im a break - the guy's into common control sex; i think he has enough problems...
every night, i kneel at the foot of my bed and thank the Great Overseeing Politicians for protecting my freedoms by reducing their number, as if they were deer in a state park. -- Chris Losinger, Online Poker Players?
-
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.
-
Aw, give 'im a break - the guy's into common control sex; i think he has enough problems...
every night, i kneel at the foot of my bed and thank the Great Overseeing Politicians for protecting my freedoms by reducing their number, as if they were deer in a state park. -- Chris Losinger, Online Poker Players?
I guess beggars can't be choosers... :)
¡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
-
leppie wrote:
Completely altering the functionality of an application with just 1 line of code
I can do that with most any program by inserting "=0" into the appropriate line. :) zero does amazing things to functionality. :)
_________________________ 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:
I can do that with most any program by inserting "=0" into the appropriate line. zero does amazing things to
disfunctionality.corrected your typo.
-- You have to explain to them [VB coders] what you mean by "typed". their first response is likely to be something like, "Of course my code is typed. Do you think i magically project it onto the screen with the power of my mind?" --- John Simmons / outlaw programmer
-
I agree 100% Isn't that the "Three Cs of Good Programming" ? C was as good a letter as any. MArk
Mark Salsbery Microsoft MVP - Visual C++ :java:
C is a fine letter. After years of working as a consultant, my spidey sense is fairly fine-tuned when it comes to code quality. My clients typically hire me when they have a problem, not when things are going well. I can usually tell the code quality in a very short time. How long does it take to track down where the problem is in the code? How long does it take to understand what the code is doing (or is supposed to be doing)? How many side-effects are caused by changing one section of code? The answers to these kinds of questions usually tell the story, and believe me, it has nothing to do with architecture, uml diagrams, naming conventions, or most of the comments in this thread. I've seen 20-line modules that were crap, and 5,000-line modules that were absolutely golden. I'm convinced that most of today's practicing programmers haven't a clue what it means to write code for the guy who comes after you. It's a bleak picture, but on the other hand, I'm a consultant, and I have more work than I can handle! :)
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.
-
Aw, give 'im a break - the guy's into common control sex; i think he has enough problems...
every night, i kneel at the foot of my bed and thank the Great Overseeing Politicians for protecting my freedoms by reducing their number, as if they were deer in a state park. -- Chris Losinger, Online Poker Players?
-
Shog9 wrote:
Aw, give 'im a break - the guy's into common control sex; i think he has enough problems...
You don't even know what InitCommonControlsEx is do you?
Yeah a soon to be legacy Win32 API for initialising the 'Extended' Common Controls found in later versions of windows.
Roger Irrelevant "he's completely hatstand"
-
Being the most expensive aspect of business software development it is also the most overlooked, instead "get it done"-itis sets in and it all rolls down hill from there. For consistency, I think the most important level of consistency is developer level consistency and not team level consistency. 1) Because it is easier to obtain and 2) because in all my years I have never seen a team, who requires team level consistencies, actually be consistent were it counts. On commenting, which is crucial, if your comments match the type of comments a machine generator for comments produce then you are not actually commenting code. Corollary to this is that automatic commenting systems do not generate comments. Thoughtful naming, if more developer learned to type the world would be a better place. Solid foundation in basic computer science principles and a complete understanding of basic programming concepts. Heh, I could go on but I shouldn't.
File Not Found
Hit it on the nail. The high level of out-sourcing and contracting usually results in a kaleidoscope of coding styles. Do people still do code reviews? I have worked in environments where critical code was given two reviews by different individuals, handed around the team and then discussed in a code meeting. These reinforced the coding standards and also enhanced the learning process. But, I am straying into team structures and leadership. Interesting topic.
-
Bah humbug! Grammar schmammar! Next yu'll kumplane abowt my speling!
¡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
That's aboot yer spelin, yer ijit!
Software Zen:
delete this; -
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
Two accounts, vote 5 with each one; simple.
Software Zen:
delete this;