CODEWITHSUNDEEP
functioncoding-stylecomments
roverred
roverred

Reputation: 1921

Better Practice for this example: Breaking up code with functions or using comments

Sometimes I get torn on whether I should leave the code in a bigger block or break them up into functions. Functions can make it more clear, as it separates the code, but I feel the clarity can sometimes be the same by using comments. My code below is a C# code where I'm initializing the Controls.

Here I can have it is a block or separate it into functions. Which of the 3 types would you prefer and why? Would your answer change if each section/category (Enable controls, Initial label values, control properties) of the code was much bigger? Maybe 5-15 lines each? Let's assume the code inside Initialize() won't be reused much except through the function Initialize(). Any other criticism is welcomed too. Thanks.

protected void Initialize()
{
    for (int i = 0; i < numOfTrackBars; i++)
    {
        //Enable controls
        trackBarList[i].Enabled = true;
        trackBarLabelList[i].Enabled = true;
        trackBarFieldList[i].Enabled = true;

        //Initial label values
        trackBarLabelList[i].Text = trackBarNames[i];
        trackBarFieldList[i].Text = Convert.ToString(0);

        //Control properties
        trackBarList[i].Maximum = trackBarMaxValues[i];
        trackBarList[i].Minimum = trackBarMinValues[i];
    }
}

Or:

protected void Initialize()
{      
    for (int i = 0; i < numOfTrackBars; i++)
    {
        EnableControls(i);
        InitializeLabelValues(i);
        SetControlProperties(i);
    }
}

private EnableControls(int i)
{
    trackBarList[i].Enabled = true;
    trackBarLabelList[i].Enabled = true;
    trackBarFieldList[i].Enabled = true;
}

Or:

private void EnableControls()
{
    for(int i = 0; i < numOfTrackBars; i++)
    {
        trackBarList[i].Enabled = true;
        trackBarLabelList[i].Enabled = true;
        trackBarFieldList[i].Enabled = true;
    }
}

The others functions being the same, so 3 for loops.

Upvotes: 1

Views: 161

Answers (2)

Adam Liss
Adam Liss

Reputation: 48310

My order of preference would be #2, #1, #3.

I find #2 the clearest because it shows exactly what you're doing: enabling, labeling, and setting properties for each item. It's easy to drill into each of those actions if you need the details, but you're not distracted by them.

#1 is next because it's also simple, straightforward, and easy to follow. You've visually separated each of the steps, so again, the details are available if you need them, but it's easy to skip over any section that isn't immediately relevant.

I find #3 both harder to read and less efficient. It's clearer to me to iterate through each item, initializing it completely, than to perform one action on all of the items, then the next action, and so on.

Upvotes: 1

BartoszKP
BartoszKP

Reputation: 35891

Comments are evil. To quote R. Martin: "comments are your failure". If you need to write a comment, it means that you have failed to write your code in a readable way, and need some additional explanation.

Why comments are bad:

  • They are written in natural language, so inherently not as precise as code and usually ambiguous (especially in multi-language teams, or among non-native speakers at different level).

  • They get obsolete. Very rarely someone quickly fixing a bug will fix the comments as well. And there is no way to verify it.

  • They are noise - additional characters which distract you from reading the actual code.

  • They bring another degree of freedom to your application's code. Even if you waste a lot of time designing a commenting policy, establishing a format of comments, and introducing precise rules on when and where to put comments, they will vary between developers. One possible reason is mentioned in the first point, other is that it's hard to write precise rules for a natural language, which is inherently imprecise. Precise definition of commenting standard needs huge amount of rules and guidelines and imposes a huge burden on developers.

Sometimes it is really hard to write something in a readable way. Sometimes things are just complicated themselves and even the simplest possible code that implements them is not easy to understand. Sometimes you need to write some non-obvious hack to meet some strange requirements of a 3rd party library. Then you write a comment, knowing that this is a communication failure but there is no other way.

Such rare comments will have their value - if someone reads a clean and readable code without a single comment, and suddenly spots one then they will know that surely this is something important that needs their attention and they need to be cautious here.

When there are lots of comments, they are just being ignored, and you won't have the possibility to inform about something really important - your comment will be lost in the sea of other comments.

The difference between the second and third version of your code is IMHO meaningless. If none of these versions is better in terms of code duplication then it seems to me that it doesn't matter which one you'll use. You could use InitializeLabelValues instead of Initialize for example though.

Upvotes: 3

Related Questions