Discussion on: Clean up your code by applying these 7 rules ⚡️

[Calin Baenen]

Honestly, I get stuck with how to clean my code, but this is my rule of thumb. What do you think?:

# Imports
import modulestobeimported;
import modulestobeimported2;


# Do <thing>.
x = thing1(); # Make "x" a thing.
completething(x);

# Related things.
y.dothingwith(x, null); # Make Y do a thing to X.


# Semi-related.
a = str(y.getdata()); # Get graphing data.



# Unrelated things.
z = extrathings(); # Comment to clarify, if it seems confusing.



# Main method.
def Main():
    pass;

The main (class and/or) method is considered unrelated to anything else, while, unrelated sections are 3 lines down, semi-related, 2, and related 1.

They don't always have to be labeled with comments, but, I think it looks neater.

One example is the CPane class from my most recent post (here).

Another is:

// Get graphing data for the money made from the server.
Tuple[] d = server.getGraphPoints("money-made");

// Graph some data.
Graph g = new Graph(
    new Tuple<int>(0, 0),
    new Tuple<int>(1000, 1000),
    d
); // Make a 1000 by 1000 graph to show the sales.


// Make a display to show the graph.
JFrame window = new JFrame("Data Graph");
window.add( g.getJPanelRepresentation() ); // Get the repr of the graph.

Again, tell me what you think of my writing style, I'd love to hear feedback.

[Emile Steenkamp]

You don't need comments to explain what your code is doing. Better practice is to use code to explain what the code is doing.

for your last example you could rather do this:

Graph graph = getGraph("money-made");
displayGraph(graph);

function getGraph(String source) {
    Tuple[] graphPoints = server.getGraphPoints(source);
    Graph graph = new Graph(
        new Tuple<int>(0, 0),
        new Tuple<int>(1000, 1000),
        graphPoints
    );
    return graph
}

function displayGraph(Graph graph) {
    JFrame window = new JFrame("Data Graph");
    window.add( graph.getJPanelRepresentation() );
}

In this example out functions are telling the developer exactly what is happening and splitting the code up into sections instead of comments. A common issue is that comments can lie. If you update the code and forget to update your comments your comments will be lying and can confuse you. If your code is readable you shouldn't need comments to explain what is happening.

Uncle Bob explains the use of comments much better in this talk:
youtu.be/2a_ytyt9sf8
and I would recommend watching the entire clean code series if you have time.

[Calin Baenen]

Is it bad, or to a disadvantage to use comments, then?

[Darlan Tódero ten Caten]

Yes, experience teaches us that comments must be the last resource to be used only when the logic is very hard to explain. Even so in most times is better to break that complicated logic into multiple small functions to be easy to read that code later.

Always try to name all variables, functions, and classes with meaningful names that self explain itself, avoiding the usage of comments.

Also, another problem with comments is that when the code changes very often the developers don't update the comments (the linter don't tell us that they are wrong now) and they don't reflect anymore the current logic of the code.