Looking at your `init` function, I would refactor it to not be so nested with if statements. Try logically inverting the if checks and returning early up near the top of the method and remove the else branches. Keep repeating this kind of refactoring on all your if statements. Eventually, you'll find that the "happy path" ends up at the bottom of the method and can return a success status without being so far indented. This style makes it easier to reason about what conditions are possible at various points in the method, i.e. you don't have to mentally compose the boolean logic conditions of all the nested if/else statements.
Also, I would generally move all implementation code out of header .h files into standard .c files. Header files are traditionally just meant to contain forward-declarations of types and methods.
Thank you for the feedback and gist, I will take it into consideration.
We use the 'happy path' style at work. It is OK. I find it has its own set of disadvantages as well. I am also not a fan of negative/negating conditions.
Whenever possible, I try to write the code the way I would explain it in plain language. This may be antithetical to the majority of modern programming, but I am OK with that.
WRT, the header files, given the size and contents of basque.c, I'd say it's just a placeholder/example file, and that the engine is by design a header-only library. Which is fine, IMO. Though the headers don't feature guards against multiple includes, which is surprising.
nested ifs work here too. i personally don't think cognitive overload is an issue because you are not composing all the conditions at once. in fact, each block should only care about one condition. but you make a good point.
tbh, i have seen nested ifs used in video game programming a lot. and i came to the conclusion that it has to do with the else clause that the return early method doesn't provide. the else clause is always doing something because games are never supposed to fail...
The cognitive overload is not just in having to mentally parse a single complex conditional check on a single if statement. It's more an aggregate effect of having to mentally compose all of the conditions of the outer if/else branches that a line of code is contained within in order to reason about the code within that branch.
I'd also add that it's a good idea to break out complex condition checks to their own independent if statements on separate lines. I'd even go further and decompose the condition expression into individual boolean variables so that if you build in debug mode you have all the evaluated values held in variables for inspection. In release mode the variables should be compiled away.
There are some practical and aesthetic benefits that come from reducing nesting and breaking apart complex if conditions:
* less horizontal scrolling in your editor
* no need to parse complex boolean expressions all stuffed into very few `if` statements
* easier ability to step through code within a debugger and follow the execution logic more exactly
* more distinct line numbers for crash dumps / stack traces to refer to in order to exactly identify which condition or evaluation is causing a failure
That last point is very beneficial when you hand your code off to someone else and they send you back a stack trace to investigate. Your code probably crashed at a complicated line of code full of boolean-combined expressions and any one of them could be at fault. All you know for sure is that something went wrong at that line number. No other hints given as to what went wrong or what the value of all the relevant variables on that line are.
I also wanted to comment on needing it because games aren’t supposed to fail. The way you actually do that is not to try to recover from errors but to surface them quickly and fix them at the point of failure. Ideally before shipping. Recovery is usually very difficult because games are a collection of very dependent state and if you don’t recover correctly letting the game continue after an error is very likely to result in all sorts of other bizarre issues happening. This can also be very subtle where the accumulation of errors leads to a sudden obvious issue and finding the root cause is very difficult. Whereas failing early and loudly makes things much easier.
They work here too, but they're unnecessary since explicit short circuits are more readable and result in cleaner code. Apart from the obvious visual improvement, it encourages you to write functions that do one thing. Excessive use of "else" and branching can be a code smell. Over time, I've started using "else" less and less. I don't remember the last time I even used an "else".
> If cond return err means everything after is an implicit else block
Right, but inverting to get to return early format means that the “else block” that needs to do substantive work becomes the if block, and it needs to be doing something substantive not just “return err”.
Which may be a valid criticism in some cases, but doesn't seem to be in this particular code base, where most of the ifs don't have an else and those that do it's log-error-and-return.
Using header files is great when starting new projects. When I wrote my first game engine, I tried to keep everything in .h files. There are two benefits:
A minor one, but still saves some time: You don't have to think about build system. Just compile a single .c file on the command line. You can quickly add and remove .h files while prototyping, without having to add/remove files to the project.
A major one: is that you cannot create cyclic dependencies. This helps to get your call hierarchy right. When using header files only, the only way to get cyclic dependency is to use a forward declaration and every time you feel like you need to do that, a big red flag is raised in your mind. And then you start to think how to do it properly. This is even more important in C++ where you have to think about responsibilities of every class. It prevents you from creating too coupled code.
When the project grows and compilation times get long, you should split all of those into separate compilation units, so that you can use multi-threaded builds (via ninja, or make -j).
It's not uncommon in game development to do 'unity builds', by basically including all code to get a single compilation unit. It can reduce build times and the compiler has more options for optimizations (inlining, mostly). This doesn't require putting everything in header files, just including the .c files gets you the same result. But if you're doing unity builds the distinction between header files and source files is basically reduced to the file extension anyway...
I think Ryan just wants a single compilation unit, for the time being. I would personally just put all the code in one file if it's this small (though I think some text editors are not good at editing one file from multiple views, so I can see that being annoying for some).
I know that using .c and .h files is the traditional way of doing it in C, and I started the engine this way, but to be honest, is there any gain to it in this scenario?
The headers are library code, and having more files just means more maintenance and build complexity. Is there another advantage I am not aware of?
The question should probably be what you gain from the header files? If you just want the simplicity you can "#include \"some_file.c\"" instead. Functionally it's no different, but it's less surprising to other people and it's an easier transition to a real build system if/when you need it. I think the reason it's being raised is because people think your writing a header only library.
In my experience, including `"some_file.h"` is more common than `"some_file.c"`. I also like knowing at a quick glance what the entry point/main file is. That's less explicit when all the files have the same extension.
There's an important difference between C++ style header-only libs, where the implementation is often done in inline code (especially for template-heavy APIs) and thus visible in each compilation unit (which is indeed bad for compile times), and "STB-style single-file libs", where the implementation is only visible in a single compilation unit.
The difference between a single .h file and a .h/.c pair is really just different packaging for distribution and integration into projects.
Here's an example I did: https://gist.github.com/JamesDunne/a94782bc39d95515f7dcc8516...
Also, I would generally move all implementation code out of header .h files into standard .c files. Header files are traditionally just meant to contain forward-declarations of types and methods.