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.
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.
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.
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 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.
16. Types say what you data means
Memory is just a sequence of bytes; bytes are just numbers from 0 to 255; what those numbers mean is described on the language type system.
For example, in C, a `char` type of value 65 is most probably the letter "A", which an `int` of value is 65 is the number 65.
Remember this when dealing with your data.
17. Cognitive Dissonance is the readability killer
"Cognitive dissonance" is a fancy way of saying "I need to remember two (or more) different things at the same time to understand this."
For example, adding booleans to count the number of True values is a mild cognitive dissonance 'cause one can think "What do you mean True plus True equals 2?"
17 1/2. The Magical Number Seven, Plus or Minus Two
"The magical number" is a psychology article about the number of things one can keep in their mind at the same time.
If you have a function, that calls a function, that calls a function, that calls a function, that calls a function, that calls function, you may be sure it will be a hell to read later.
Think more about: I'll get the result of this function, then pass it to the second function, get its result, pass to the third an so on.
18. Shortcuts are nice, but only in the short run
A lot of languages/libraries/frameworks add a way to make things shorter, reducing the number of things you need to type.
But, later, that will bite you and you'll have to remove the shortcut and do the long things.
So learn what the shortcut does before using it.
19.1. Write steps as comments
If you have no idea how to start, describe the flow of the application in high level, pure English/your language first. Then fill the spaces between comments with the code.
Better yet: think of every comment as a function, then write the function that does exactly that.
@juliobiason I am too :)
@juliobiason err... Nope. Sometimes you just need dive in and explore the stuff.
@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:
@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.
functional.cafe is an instance for people interested in functional programming and languages.