GUIDELINES Course

Code guidelines

Guidelines are used to make your code more maintainable. They are including naming conventions, styling conventions, or everything related to the project. You will learn about famous mnemonics such as SOLID, DRY, YAGNI, and KISS.

You may have learned in other courses that we have

  • methods: test-driven, model-driven, ...
  • design patterns (and anti-patterns)
  • frameworks

Using these, you will be backed by the knowledge, experience, and code improved by a lot of developers before you. But you will still have to write some code by yourself, and this course is a gathering of programmers principles that may help you write your code.


Me

Here are some of my troughs before starting.

I think you should really consider using frameworks and tools created by other developers (If they are still maintained) rather than writing everything from scratch. This should

- make the "setup" longer (installing a framework might not go smoothly)
- force you to learn a new framework/... 
+ broaden your horizons (since you will learn how someone else tackled your need)
+ reduce the maintainer workload (since another maintainer would deal with the framework)
+ it should reduce your workload too (since you should have less code to write)
+ reduce the complexity of your code (if not, pick another or publish your own framework)

Aside from that

  • I think you should properly document your code (no too much documentation, consider the maintainer when coding)
  • you shouldn't copy-paste code from another part of your code (anyone will tell you this one)
  • give relevant names to your functions/variables, but only when that's useful, like i is better than index if i is a simple index. Declare them at the start of a bloc.

Principles

Don’t repeat yourself (DRY): Do not copy-paste code, make a function. Otherwise, you need to remember that you will have n places to patch if you found a bug, and that's not worth it. You should also use constants rather than writing, again and again, a value like "toto" in your code.

You ain't gonna need it (YAGNI): don't write code unless you need it.

Keep it simple, stupid (KISS): simple code means less code. It's easier to debug and modify, so don't make things complicated.

Code For The Maintainer: write your code like you will be the one to maintain it. It's hard to maintain some unreadable code, isn't it?


Practices

Separation of concerns (SOC): simply separate your code according to what part of the program they are dealing with. This may also us to reuse some parts in another application. For instance, you should not have a class called "UndoAndRedo" or "UndoRedo".

The Rule of One or Curly’s Law: a part of your code must do only one thing.

Rubber duck debugging: when you got a problem with your code, try explaining it to a rubber duck (canard en plastique in French). Sometimes, simply explaining your problem to "someone", helps in solving it. Talk to your rubber duck :)

Murphy's Law: "Anything that can go wrong will go wrong.". Don't think "xxx won't do that" and skip some code, because "xxx" will (calling a method using the wrongs parameters, ...).

Do The Simplest Thing That Could Possibly Work: Simply write as little as possible, or think about the easiest solution for your problem and code it. You may improve your code later through.


SOLID

SOLID is an acronym for

  • S (Single): Do one thing
  • O (Open/Closed): use inheritance to modify a class like
    • if you want to modify, you can
    • but if you want to add a public member, then inherit the class
    • "Open for extension, closed for modification"
  • L (Liskov substitution): variables having the type A can store inheritors of A
  • I (Interfaces segregation): split big interfaces into a bunch of small ones
  • D (Dependencies inversion): create layers using interfaces and abstract classes

This is a bit more complicated and will require knowledge in Oriented-object. You should check SOLID principles on Wikipedia.


Guidelines

I started this course because of this website https://suckless.org/, "software that sucks less". Well, dunno about their software, but the website sucks 🙄. Still, here are some of their ideas, mixed with others (see references)

  • LICENSE + README.md inside each project
  • declare all variables at the start of a bloc
  • add the * (pointer star) after the type, not the name
  • line length: less than 79 characters
  • declare your variable then give them a value
  • use constants (const) or #define
  • use sys/queue.h rather than your handmade lists
// a space after include, ordered by name
// <> before ""
#include <stdio.h>

// not a&&b but a && b
if ( a && b ) { // "{" on the same line, space after the "if"
}

// for a function
void
fonction_name( int a, ... )
{
    
}

You should do the same before starting a project, set things up with yourself and your team.


meme


best practices (GitHub lookup summary)

After discovering this repository, which is quite good for explaining what you mustn't do, I looked on GitHub's "best-practices repository". Here is a summary of the repository above and many others.

Style Logic Others
use a proper variable name log errors add a README file

do not mix naming styles (camelCase, snake_case) unless it's intended (like snake_case_CamelCase, that may be used for function's names in C)

remove unused code/variables (NO "for later") add a LICENSE file (even if it's MIT).
do not mix formatting
  • if you can use " or ': pick one!
  • if you are adding a ; at the end of the line, do it everywhere
  • same indents for the whole file
  • ...

To summarize, you should define guidelines before starting.

If you ever created a function dealing with more than one task then you should split it.

split a long line on multiples lines Do not make an "if" statement directly inside one, try merging their conditions.
check the argument types
(if needed, the language matter)

Sources

Guidelines