Click here to Skip to main content
14,607,954 members

How to Write Good Code

Rate this:
4.87 (37 votes)
Please Sign up or sign in to vote.
4.87 (37 votes)
22 Nov 2015CPOL
Each function should answer "how-what-why."

My first tip!

This is not a long tome on software architecture.  This is simply about how do to write good code. Code consists of functions, and this is what a function should look like (using C# style as an example):

// A comment describing why the function exists
void WhatTheFunctionDoes()
{
  ... how the function does what it says it does.
}

That's it! If you follow the "why-what-how" approach, the quality of your code will start to improve! Here's a real life example:

/// <summary>
/// The user can get an instance of a service implementing 
/// the specified interface, but only if the service is 
/// registered as supporting instance creation.
/// </summary>
public virtual T GetInstance<T>()
  where T : IService
{
  VerifyRegistered<T>();
  VerifyInstanceOption<T>();
  IService instance = CreateInstance<T>();
  instance.Initialize(this);

  return (T)instance;
}
  1. The "why" is clear -- we're supporting a need the programmer will have for creating service instances.
  2. The "what" is clear -- the function returns an instance of the specified generic type T.
  3. The "how" is clear -- there are four function calls that describe how this function works.

Here's a simple guideline for figuring out when to break a function apart into smaller functions:  

If your function has "how" fragments that would benefit from "how", "what" or "why" comments, then this is great indicator that you should move those fragment into separate functions where the the function name describes "what" and embodies "how."  In other words, when you could write a comment in the body of the code that answers one of those questions, you need to move that code into a function that answers the "what".

Recurse that process until the function's name answers "what" and the body of the function clearly describes "how", then for each function you created, write an intelligent "why" comment.

Now go forth and code better!

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Marc Clifton
Architect Interacx
United States United States
Blog: https://marcclifton.wordpress.com/
Home Page: http://www.marcclifton.com
Research: http://www.higherorderprogramming.com/
GitHub: https://github.com/cliftonm

All my life I have been passionate about architecture / software design, as this is the cornerstone to a maintainable and extensible application. As such, I have enjoyed exploring some crazy ideas and discovering that they are not so crazy after all. I also love writing about my ideas and seeing the community response. As a consultant, I've enjoyed working in a wide range of industries such as aerospace, boatyard management, remote sensing, emergency services / data management, and casino operations. I've done a variety of pro-bono work non-profit organizations related to nature conservancy, drug recovery and women's health.

Comments and Discussions

 
Questionself-explainatority over commentation Pin
Mr.PoorEnglish14-Jan-16 1:16
MemberMr.PoorEnglish14-Jan-16 1:16 
GeneralI like the "why" part Pin
flyingxu10-Dec-15 14:01
Memberflyingxu10-Dec-15 14:01 
QuestionUse of comments Pin
Joseph Webster, CISSP2-Dec-15 11:49
MemberJoseph Webster, CISSP2-Dec-15 11:49 
AnswerRe: Use of comments Pin
Marc Clifton3-Dec-15 3:09
mvaMarc Clifton3-Dec-15 3:09 
QuestionOne more improvement Pin
wraithnath26-Nov-15 3:29
Memberwraithnath26-Nov-15 3:29 
PraiseNice job Pin
Member 466290325-Nov-15 20:50
professionalMember 466290325-Nov-15 20:50 
QuestionWriting good functions Pin
Member-243269624-Nov-15 3:11
MemberMember-243269624-Nov-15 3:11 
Question"wherefore", "what", "how", "why so and not otherwise" are four questions to any function (class/method/module) before its creation. Pin
DimaZavr23-Nov-15 5:45
MemberDimaZavr23-Nov-15 5:45 
AnswerRe: "wherefore", "what", "how", "why so and not otherwise" are four questions to any function (class/method/module) before its creation. Pin
flyingxu10-Dec-15 14:04
Memberflyingxu10-Dec-15 14:04 
Questioncomment Pin
KhabirSoft23-Nov-15 5:28
MemberKhabirSoft23-Nov-15 5:28 
GeneralMy vote of 5 Pin
Santhakumar M23-Nov-15 3:08
professionalSanthakumar M23-Nov-15 3:08 
PraiseNice Pin
Simon_Whale23-Nov-15 0:18
professionalSimon_Whale23-Nov-15 0:18 
PraiseMy vote of 5 Pin
Liju Sankar22-Nov-15 18:01
professionalLiju Sankar22-Nov-15 18:01 
GeneralMy vote of 5 Pin
JayantaChatterjee22-Nov-15 17:02
professionalJayantaChatterjee22-Nov-15 17:02 
QuestionCoding better Pin
Vivi Chellappa22-Nov-15 16:00
professionalVivi Chellappa22-Nov-15 16:00 
SuggestionNitpicky, but... Pin
wvdhouten22-Nov-15 13:00
Memberwvdhouten22-Nov-15 13:00 
GeneralRe: Nitpicky, but... Pin
Marc Clifton23-Nov-15 3:47
mvaMarc Clifton23-Nov-15 3:47 
GeneralRe: Nitpicky, but... Pin
wvdhouten23-Nov-15 4:03
Memberwvdhouten23-Nov-15 4:03 
GeneralRe: Nitpicky, but... Pin
wvdhouten23-Nov-15 4:07
Memberwvdhouten23-Nov-15 4:07 
GeneralRe: Nitpicky, but... Pin
Yusuf23-Nov-15 5:36
MemberYusuf23-Nov-15 5:36 
PraiseMy vote of 5 Pin
Afzaal Ahmad Zeeshan22-Nov-15 9:01
mvaAfzaal Ahmad Zeeshan22-Nov-15 9:01 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Tip/Trick
Posted 22 Nov 2015

Stats

29.5K views
27 bookmarked