Code and API cleanup #6569
Comments
|
There are definitely places we got things wrong (SDL_Render's function naming is pretty inconsistent, for example), but I don't think we need dogma about making all API calls match a specific pattern (SDL_SubsystemVerbNoun or whatever). I'm pretty happy with the current coding style (One True Brace, 4 spaces no tabs, etc). In fact, I started adopting it on other personal projects after decades of using a style that is very different. :) |
|
Having a rigid convention helps in auto completion. For example if we stick to However we can also have other styles for specific common requests (like
With that we can almost immediately identify which function should be called if one want to initialize a module and use it. SDL_Renderer *rdr;
rdr = SDL_CreateRenderer();
SDL_RendererDrawRect(rdr, ...);
SDL_DestroyRenderer(rdr)SDL_Joystick *js;
if (SDL_IsJoystick(1)) {
js = SDL_OpenJoystick(1);
SDL_JoystickGetAxis(js);
SDL_DestroyJoystick(js);
} |
|
we could have both with some kind of aliased |
|
I kind of like this approach, suggested by @furious-programming:
I am not talking about a dogmatic requirement, but about a convention that is clear, easy to understand and compatible with IDE tools (code completion, searching text etc.) — it's just a reasonable approach. Eskil Steenberg said something about this in the video entitled. "How I program C" — it is a really good naming that makes working with code much much easier. The only difference I use from Eskil is a different approach to getters and setters. Eskil uses Regular functions:
Getters (same pattern for setters):
See how the words in the identifiers stack up — the beginning fragments are consistent, which is easy to filter, while getters and setters are easy to distinguish from regular functions. Three variants of getters should also be taken into account, i.e. the prefixes |
|
Below is an example from the code of my current project, showing how fabulously easy it is to guess identifiers and how function names work with code completion window and its filtering:
The convention is more or less the same as the current SDL, except that I use the |
|
I think it should be quite easy to turn all SDL api, into SDL_SubsystemNounVerb. |
|
eg, using category: |
|
(with a bug "render vs renderer" inside) |
|
while it makes search easy, it makes code less readable |
|
@1bsyl: why ”less readable”? It is the use of a specific pattern that allows you to increase readability, because the construction of identifiers is uniform and always predictable. Source code is not a poem — identifiers should be constructed so that you don't have to memorize them, instead of following the rules of English sentence formation. Your proposal (a list of new function names) is not good because, for example, you can't filter out audio device functions because you don't use the Different languages and for different purposes use a prefix system in which the common parts of identifiers are at the beginning of them. Unfortunately, such a system is mainly used for naming constants, while there is chaos in the names of functions. Meanwhile, nothing stands in the way of using such a naming system in the case of functions (as well as constants and data types), introducing uniformity and order in the entire library. |
|
I mean "code less readable", because I think one spends more time reading code, than searching for function name. and so reading should have more importance than searching for a function. But this is just a point of view. yes, the category isn't perfect. this is a 5 min proto. can add the AudioDevice category to try. l'll update the list. |
|
updated |
|
Okay, so after discussion with @icculus, I think we're going to try with the following conventions:
I'm going to start with SDL_audio.h as a first example for discussion and we can move on from there. |
|
Okay, the complete change proposal is up, and #6876 has been updated with the list of headers that aren't touched. One nice thing is that with this new proposal, only 9 out of 79 API headers are being touched, which means that this is largely in line with how we've been designing the API. Comments welcome! |
|
I write my code |
|
The bulk of this work is done! Feel free to open new issues for additional cleanup or to revert bad ideas. :) |
|
I've just been going through the SDL2 to SDL3 migration and noticed some possible niggles: Should we rename functions like And I noticed missing oldtype #define for the following: |
Yep, this is done in a06a593. |
There are no direct equivalents for these functions. Instead you get a list of device IDs and operate on those with new functions. |
Review ideas in #3519 for coding style and API conventions
Discussion?
@libsdl-org/a-team
The text was updated successfully, but these errors were encountered: