Out of the blue, I thought another presentation I can make for people starting UNI:

"Things I Learnt the Hard Way in 30 Years of Software Development"

Follow

1. Monitoring.

After writing a lot of metrics for a project in a previous life, not adding any support for Prometheus makes me feel nervous of deploying my code in production.

2. Tests are good, integration tests are gooder.

I'm currently writing tests for a single module only (e.g., only tests for the "view" layer). It gives me some idea of what is right and what is wrong, but in no way I feel those tests say my code is doing what it should do.

3. Tests make better APIs

We build stuff in layers. Tests allow use to see how the API of a layer behaves and we can make better APIs by just checking our struggles writing tests.

4. Future thinking is future trashing

Solve the problem at hand. Don't think "We can do this in a more general way and, in the future, it will be easier to add more". Adding more will never come and you'll have to deal with a pile of trash.

Solve one problem, then solve the next. A patter of problem will emerge -- or not.

(For a second, I thought "Well, I'll have to stop and think a lot about this", but whatever came on the top of my head is a very good start, IMHO.)

5. Code reviews are for architecture, not style

Do not complain about a misplaced semi-colon or a "missing space before parenthesis" in a code review. That's not the forum for this -- unless you found an architectural problem, then you can point both.

5 1/2. Code formatting tools are ok, but are no silver bullet

Computers are very flexible into reading code, but humans are not.

(I may even say that, if the tool is moving a lot of your code, there may be a real architecture problem with your code.)

6. Documentation is a love letter to your future self

Yeah, it's tiring to write the damn documentation on every freaking function, but your future self will thank you for letting the code explained on what it's doing.

6 1/3 The documentation of a function is its contract

The documentation should reflect the code; if it doesn't, you have a problem with your code, not your documentation.

6 2/3. Documentation with an "and" means you're doing it wrong

A function should do one thing and one thing only. If you have to add an "and" to its description, it probably means the function is doing two things and you should break it apart.

6 3/3. Good languages come with integrated documentation

If the language comes with its own way of documenting functions/classes/modules/whatever and it comes with even the simplest doc generator, you can be sure all the language things and libraries will have a good documentation.

But languages with no integrated documentation will most of the time have bad documentation.

7. When it is time to stop, it is time to stop

Learn when you can't code anymore. Learn when you can't process things anymore. Don't push beyond it, it will just make things worse in the future.

8. A language is much more than a language

A programming language is that thing that you write and make things "go". But it has much more beyond special words: It has a build system, it has a dependency control system, it has a way of making tools/libraries/frameworks interact, it has a community, it has a way of dealing with people.

Don't pick languages just 'cause they easier to use.

9. Code of conduct protect _you_, not _them_

When you're beginning with any language/library/framework, check their CoC; they will protect _you_ from being harassed for not immediately getting what is going on instead of blocking you from telling them what you think.

(Addendum: Most of the time, people against CoCs are the ones that want to break it in the first place.)

10. Learn to say no

Sometimes, you'll have to say no: No, I can't do it; no, it can't be made in this time; no, I don't feel capable of doing this; no, I don't feel comfortable writing this.

11. You're responsible for the use of your code

This is hard. Very very hard. It's the difference between "freedom" and "responsibility".

There is nothing wrong in writing, for example, a software to capture people's faces and detect their ethnicity, but you have to think about what that will be used on.

12. Understand and stay way of cargo cult

"Cargo cult" is the idea that, if someone else did, so can we. Most of the time, cargo cult is simply an "easy way out" of a problem: Why would we think about how to properly store our users if X did that?

"If BigCompany stores data like this, so can we".

"If BigCompany is behind this, this is good."

13. Companies look for specialists but keep generalists longer

If you know a lot about one single language, it may make it easier to get a job, but in the long run, language usage dies and you'll need to find something else. Knowing a bit about a lot of other languages helps in the long run, not to mention that may help you think of better solutions.

"A language that doesn't affect the way you think about programming, is not worth knowing." -- Alan Perlis

14. Data flows beat patterns

(This is personal opinion) When you understand how the data must flow in your code, you'll end up with better code than if you applied a bunch of design patterns.

14 1/2. Design patterns are used to describe solutions, not to find them

(Again, personal opinion) Most of the time I saw design patterns being applied, they were applied as a way to find a solution, so you end up twisting a solution -- and, sometimes, the problem it self -- to fit the pattern.

First, solve your problem; find a good solution; then you can check the patterns to know how you name that solution.

Show more
Show more

(Addendum to "generalists" rule: For a long time, I kept a simple programming rule: The language I'm playing at home should not be the same language I'm using at work. This allowed me to learn new things that later I applied in the work codebase.)

(Addendum to the "integrated documentation": The same can be said to languages with integrated testing frameworks: They come with good tests.)

@juliobiason Much of cargo-culting is:

1. Ignorance of true meaning or mechanism expressed as mimicking a form or pattern.

2. Signalling membership within a specific group or tribe.

3. A response to fear and lack of understanding by management or clients of meaning or mechanism, by mimicking a form or pattern.

There's a strong similarity to this and fads and fashions generally, in an information-theoretic fashion. Not specifically mentioned here, but similar idea:
old.reddit.com/r/dredmorbius/c

@juliobiason At the same time I have to argue that you might have to allow for some bad usage in order to get the most good usage out of your software.

So while I don't disagree with having the best, most positive, impact you can, it does worry me for programmers to be blamed for how their software is used.

@alcinnz Had a long discussion with a coworker a few days ago exactly about this.

"This is against free software, isn't it?" and he was right.

But I really feel we should think how our apps can be misused and worry about, instead of focusing on the happy path.

... or maybe it just helps me with my continuous pessimism about software.

@juliobiason There is a path you can take which (depending on who you ask) isn't against free software. It certainly meets the definitions, and some nuance in Stallman's speeches.

If you're worried enough about your software falling into the wrong hands you don't have to publish it publically. In that way you can mostly decide who gets access to your software whilst still giving those people full software freedom over that program.

@juliobiason i disagree strongly for this

if there's an architecture problem, the code review should consist entirely of "where's the design doc for this?" and following up on your concerns there

Style violations that can be automatically enforced should be. (clang-format for C/C++)

Code reviews are appropriate for comments like "this should be multiple functions" or "this is in the wrong file".

@riking Kinda agree, 'cause, to me, "this should be multiple functions" count to me as architecture, not style.

The filename thing feel a bit like a gray area, 'cause most languages outside C/C++ that I can remember from the top of my head (Rust and Python) use the filename as module name, so "this is the wrong module" gets really weird if it is a code style or architecture...

@riking " This structure/function should be in that other module" counts like architecture problem, IMHO.

But "This module has the wrong name"... well, if you have a well define code style, then probably yes.

(When I wrote that, I was thinking about lengthy reviews full of "You left a space at the end of the line here".)

@juliobiason I'm talking architecture as in "this program gets data from system X and Z and moves it to system Y" or "we're adding a cache for non-logged-in requests".

Owch, a review of tens of comments of minor style violations should just be one "Please fix style for the entire [diff]."

@riking > I'm talking architecture as in "this program gets data from system X and Z and moves it to system Y" or "we're adding a cache for non-logged-in requests".

Ah.

Maybe "this should be two functions" is a design problem, then?

I mean, I still don't see as an architecture problem...

(Just trying to find the proper description here, I'm going to compile all points in a blog post later.)

@juliobiason I think it's a fine term to use in a blog post as long as you define it first. (Maybe "code architecture" as opposed to "system architecture"?)
Sign in to participate in the conversation
Functional Café

functional.cafe is an instance for people interested in functional programming and languages.