Click here to Skip to main content
13,193,600 members (41,864 online)
Click here to Skip to main content
Add your own
alternative version

Stats

18.7K views
27 bookmarked
Posted 22 Nov 2015

How to Write Good Code

, 22 Nov 2015
Rate this:
Please Sign up or sign in to vote.
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
United States United States
Marc is the creator of two open source projects, MyXaml, a declarative (XML) instantiation engine and the Advanced Unit Testing framework, and Interacx, a commercial n-tier RAD application suite.  Visit his website, www.marcclifton.com, where you will find many of his articles and his blog.

Marc lives in Philmont, NY.

You may also be interested in...

Pro
Pro

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
protectorMarc 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
Santhk23-Nov-15 3:08
professionalSanthk23-Nov-15 3:08 
PraiseNice Pin
Simon_Whale23-Nov-15 0:18
professionalSimon_Whale23-Nov-15 0:18 
PraiseMy vote of 5 Pin
Dev_00722-Nov-15 18:01
professionalDev_00722-Nov-15 18:01 
GeneralMy vote of 5 Pin
JCahyaatnttearjee22-Nov-15 17:02
professionalJCahyaatnttearjee22-Nov-15 17:02 
QuestionCoding better Pin
Vivic22-Nov-15 16:00
memberVivic22-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
protectorMarc 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
professionalAfzaal 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.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.171018.2 | Last Updated 22 Nov 2015
Article Copyright 2015 by Marc Clifton
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid