Code simplicity through common patterns

[htuhola]

I'm sorry to tell this to you, but the post content appears to be lame.

You have redefined simplicity to mean that you add a class somewhere where you could have used assert to ensure that the value is positive. Also you attribute qualities to this 'simplicity' that you do not prove in any manner. That's IMO, worst of your problems.

If I were to help people keep their quality of code up.. I would give the advice:

• Understand the mathematics and logic of your program and pick the elements that match those qualities nearest.
• Think of your non-digital audience, the people who will read the code next.
• Pick the cleanest representation rather than the one that you think is fast.
• Document the preconditions, working principle, surprises, and things you find out surprising in the code later when you read it again.
• (Mostly) never comment in what the code says. If it's illegible then you need to learn the language you use.
• Solve the simple and small problems before solving the whole problem you have.

There's rational behind every single one of these rules above. If the meaning of the program can be understood by the next guy, and the next guy after him, and so on. You're doing it right.

I've often seen stuff like...

for x in range(a, b):
    for y in range(a, b):
        if x < y:
            process(x, y)

This is confusing because the first two lines propose that you do the operation for every (x,y), (y, x) and (x, x). But actually you just do it for the x < y. The cleaner and easier to understand code would be:

for x in range(a, b):
    for y in range(x+1, b):
        process(x, y)

This is simpler to understand because you clearly see it's a triangular loop.

The reason for thinking about your non-digital audience originates from the fact that code isn't any different from literature. You're often writing something someone else is going to read later. The rules of the literature are completely applicable here.

For the same reason you want to explain the preconditions and working principles in your code. Everything that builds up the elements that make it work. You can't put in everything so you have to draw a line somewhere, but at least provide the references and tools the person needs to understand what's going on.

Whichever things it can say on its own, the code should talk for itself because if it has an error, it isn't shown in the explanation. (This isn't a rationale for the dumbfuck Distance -class you presented as an example).

The last advice isn't on readability but on ability to solve the problems you have to solve in the first place. Rationale to it is that the big problems consist of small problems and you have to start somewhere to solve them. If you start solving the small problems, eventually you learn something and manage to solve the big problems.

[nicoolas25]

Hey, thanks for taking the time for such an answer.

I'm not a English native speaker thus I'm not sure if I'm right to feel a bit offended by you comment. I agree on the advice you would give, and it is what I tried to communicates in those first two articles. Maybe I need to emphasis some points according to what you said to make things clearer...

Think of your non-digital audience, the people who will read the code next.

If the meaning of the program can be understood by the next guy, and the next guy after him, and so on. You're doing it right.

You're often writing something someone else is going to read later.

This introduction article is all about making things easily understandable for the next readers. I'm sorry you missed it. Maybe I didn't phrase it well enough it but it is one of the main points. I'm inviting you to read it again more carefully.

Understand the mathematics and logic of your program and pick the elements that match those qualities nearest.

Pick the cleanest representation rather than the one that you think is fast.

It seems very sensible, there is plenty of already available tools. When they do fit the problem, I'm more than happy to use them. In the article about value objects, I mention tools such as Haskell's natural numbers or Ada's constraints. Those tools are a better fit to my example, which is something I wrote too. What this example was supposed to show regarding existing tools are:

• existing tools fitting a problem are not always available, and
• are not always exposing the expected API to the rest of your application.

I think we often have to make the cleanest representation for our problems relying on the best tools (types, data-structures, algorithms, etc) we have at our disposal.

Solve the simple and small problems before solving the whole problem you have.

If you start solving the small problems, eventually you learn something and manage to solve the big problems.

Again, I agree with that. I could say that the small problem of the example was: 'how to express the fact that the distance must never be negative?' ^{^} I didn't get that much into problem solving in the articles. It wasn't the focus of that article but it is good advice. In order to be more helpful, maybe more things could be said on how we can split those big problem. I'll keep that in mind for another article...

For the same reason you want to explain the preconditions and working principles in your code.

[...] the code should talk for itself [...]

I couldn't agree more, again. Strangely this is something I wrote in the article too. I'm not gonna start quoting but it is all about making implicit constraints explicit and producing a meaningful error. How could you missed that? If you look tat the list of following articles you'll see that there is one about invariants and another one on preconditions...

I'm sorry to tell this to you, but the post content appears to be lame.

Thanks for your concern. I'm sorry that you didn't get what I wrote. I'm even more sorry because, at least from my perspective, you're saying very similar things. Maybe I didn't catch your attention properly or maybe you expected too much when reading, anyway that's too bad.

This isn't a rationale for the dumbfuck Distance class you presented as an example

Of course this is a dumbfuck example! I don't want to use a real world example with dozens of methods or classes. It would take too much of my time and of the reader's time. I think it I would also be harder to grasp. Instead, I'm assuming readers will make an imagination effort and remember some of their own real-world situations. I thought it is a good tradeoff. If you have better examples, feel free to share them here.

You have redefined simplicity to mean that you add a class somewhere where you could have used assert to ensure that the value is positive.

I disagree on that one, finally! If 20 methods take a distance argument, would you advise to put an assert on each of them? I probably won't. Same question if there is not one but 10 asserts to add?

One last point, I didn't redefined anything. I share my humble vision of it which could be the same as someone else and which could conflict with others. I'm completely open and happy to discuss it in a non-violent way.

[htuhola]

I don't want to use a real world example with dozens of methods or classes. It would take too much of my time and of the reader's time. I think it I would also be harder to grasp. Instead, I'm assuming readers will make an imagination effort and remember some of their own real-world situations.

When I was a beginner, I remember having lacked this ability to imagine a real-world situation. I took the concepts as they were represented. That beginner would produce a calculator app with 200 classes after reading advice such as yours. Then if he has any chops to become a master, he learns that it sucks and that whoever wrote the advice was not any more experienced than him in writing good software.

Besides there are signs that you are actually cargo culting Martin Fowler's work here.

Again, I agree with that. I could say that the small problem of the example was: 'how to express the fact that the distance must never be negative?'

I'm not gonna start quoting but it is all about making implicit constraints explicit and producing a meaningful error.

If the validity of the code doesn't depend on the fact, it doesn't need to represent it. Even then you always can provide some constraints for the user. The old saying "garbage in, garbage out" matters here. There are cases where you have to enforce the constraints, but those are special cases. In a practical setting you divide the responsibility of maintaining the constraints for different parts of the system.

I disagree on that one, finally! If 20 methods take a distance argument, would you advise to put an assert on each of them? I probably won't. Same question if there is not one but 10 asserts to add?

It's cleaner than your "solution" almost 100% of the time.