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.
-
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; -
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:
Therefore, good code starts with a good client.
Ah, the Holy Grail. Been taunted by any Frenchmen lately?
Software Zen:
delete this; -
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.
As a former mainframer gone pc over 20 years ago we had a very simple guide by which to judge good code. It was known more or less as a developer's signature-style. The better and more legible the style the better the code would be because of the effort to not only design it properly to present itin an elegant fashion. This of course was all before we had source-code beatifiers and syntax highlighting. However, if you review Steve McConnell's "Code Complete" you will find much of this original context as part of his many recommendations. For example, well indented code has been found to eliminate up to 30% of initial coding errors. As a result, its not the comments or the amount you indent but your own personal style that makes it your signature in the development world. People will come to know that signature and many will emulate it if it is well done. It is the naturtal beauty of the code we design and implement that defines its quality not its specific parts. That being said, my code is consistent in style whether I right a 10 line script or a 1000 line module. My comments are always the same breaking out each section of code in a method to easily readable parts. And I do not use fancy algorithms making it difficult for new technicians to understand what I am doing. My code is straight-forward and very simplistic following the old adage of "KISS" (Yes, it has an extra "S" for "stupid"...)
Steve Naidamast Black Falcon Software, Inc. blackfalconsoftware@ix.netcom.com
-
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:
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.
It is perfectly normal in all other forms of documentation to refer to other texts, books, manuals, or whatever, so it has always struck me as strange that techies seem so averse to putting such references into their inline code. Why not say something like:
/// This object follows the WoBBliE desigh pattern construction. /// See "Outside the Factory Walls" by Hoot & Annie.That gives the guys the opportunity to educate themselves, so you win on two counts. You don't have to rewrite a book that's already been written, especially inside a code editor. Inline doc is for explaining minute details, not for giving overviews. -
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.
Josh Smith wrote:
You know what they say about common sense, right...
I can't understand whay we call it "common", when it's anything but.
-
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.
I agree with your 3 attributes. What makes code good for me may not be the same as what any particular reader may consider good, and others may have better ideas. Whatever is done, doing so in moderation is essential. The only thing in which moderation is no virtue is excellence. That said... Sensible Comments - My comments should allow a professional developer to know what I am doing in code by just reading the comments. That is really helpful 5 years later when I come back to my code to update it. I use a header in each code module that explains the 10,000 ft overview of "this is what I do", along with a change history (when, who, what). I also use a header above each method or property code block that explains the input/output and what the method/property does. If it is intuitively obvious what it does, then I keep the comment short. Very short. In the code, I use short, one-line comments for most chunks of code to explain the process as it unfolds. Longer comments are useful for more complex processes. Even though some languages (VB comes to mind) are more intuitive than other more cryptic languages as to what the code is doing, it won't necessarily be so obvious to non-VB programmers, so I use comments anyway. I usually accomplish the same task that psuedocode does by writing comments describing the process, then coding to it only after I have finished the comments in an object. Don't ignore, nor go overboard with, OOA/OOP - Spaghetti objects are just as bad as spaghetti code. I hate code that I inherit where someone has gone nuts adhering to the tiniest principles of OOA/OOP like some Pharisee running a string from his home so he can walk farther on the Sabbath. Common sense is an uncommon virtue with OO bigots. I hate code where the author has forgotten the practical meaning of encapsulation. I know sometimes processes can be very complex and require a lot of objects, but I remember the KISS principle when creating my OOA. For example, one program I inherited had no fewer than 14 object modules just to do a login - and that is not counting the data access layer. All it needed was an object class for the login business rules and a UI object to login with. Multilevel logging - I like for my app to have a globally accessible log object that my code can use to log things like performance, process steps, user activity, errors, etc. and a setting that tells the log object what to actually write and what to ignore. I can set the log to record o
-
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's anything but.
-- 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
-
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.
how about some common sense?
-
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.
All good points when considering the implementation of a particular piece of code. Step up a level and I find the best code to be the code that accepts changes the most gracefully without weird side effects and bugginess popping up. Most code is written once and maintained for years afterwards (thankfully, not by the original writers). It often has extra bells and whistles added in over time. So, the ability to maintain and extend it with little effort counts for a great deal. Many would say I'm really taking about design, but I've seen good designs lobotomized by poor implementation to the point that the design cannot be easily extended as intended, so there's clearly a good-implementation component to make a good design work right. I think that component goes beyond good comments, good naming, good library use, etc.
patbob
-
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