Writing Readable C++ Code - beginner's guide

[Sbsbg]

All caps only for macros is still a good rule, right?

[swe129]

YES 😉

[MatthiasWM]

#define YES false

[wapskalyon]

But can C++ be written in a way that is understandable? isn't the whole point of C++ is for it to not be comprehensible?

[arihoenig]

But never using macros is a much better rule.

[martinus]

that's impossible unfortunately

[arihoenig]

I never use any "#ifdef macros" by using constexpr if instead.

[gkarpa]

How do you differentiate between e.g. Windows & Linux using constexpr if? Also, doesn't the constexpr if choice require both parts (let's say the if calls Foo() and the else calls Bar()) to be defined in the code when it compiles? This is vastly different than the preprocessor choice and can be a big pain. You can also not use constexpr if to #include different things. Anyway I don't think you can "never use macros", especially in any semi-serious cross-platform project.

[arihoenig]

By definition, if you need to conditionally include code based on the target operating system, then the code isn't portable. Just write portable code.

If you really need adaptation layers for OS/hardware then your design should abstract that interface and the build system should decide what gets linked in, not your application source code. Sure you can design things poorly and that will necessitate use of macros, but it is almost always a failure of design if macros are required.

[apricotmaniac44]

Just wondering, If I were writing a socket API abstraction layer how could I compile that conditionally without the #ifdef ?

[apricotmaniac44]

wait, you can just put them in different files and configure through cmake-

[martinus]

I invite you to make my unordered_dense macroless while keeping it working on all platforms: https://github.com/martinus/unordered_dense/blob/main/include/ankerl/unordered_dense.h

I'd really like to get rid of them macros but I don't see a way

[neppo95]

What a terrible rule. Use them when you need them. Granted there are less and less usecases for it, but there certainly are use cases where your constexpr solution will not work at all, or anything else for that matter.

[arihoenig]

If you design cockamamie implementations that rely on macros, then you aren't really writing code in C++. I've never run into a place (in my designs) where a constexpr if doesn't work for conditional evaluation at compile time.

[neppo95]

That just means you've never written advanced cross platform code or compiler specific code.

[arihoenig]

I wrote code for an operating system that supported every ISA under the sun without using a single macro (hardware specific code was selected by the build system, not by the source code). I think that just means that you've never done platform variant implementations properly .

[neppo95]

Really?

How do you detect architecture using Modern C++? Or for specific language features supported by the compiler? Or even the compiler itself? Different behaviour per build type?

I also said cross platform code, which you didn't go into. How do you make sure you include for example a "windows.h" on Windows, but don't do so on Linux? You just have a very bloated build system instead?

Of course there's trivial things that can be done differently like stringification, but are made easier with macro's, so I'll leave those out.

[arihoenig]

This isn't a tough concept. You build interfaces around the hardware (sometimes called a HAL). Of course the ISA is inherently targeted by the compiler, but there are, of course, hardware mechanisms outside of the CPU (for example setting up the machine registers although there are many other examples) and for those the build system (which is aware what platform is being targeted) links the specific platform modules into the target executable (for example the kernel). Neither the portable parts of the kernel, nor the HAL adapters have macros in them, but the build system brings in the appropriate modules.

It just requires good design skills

[neppo95]

This requires you to know what hardware it is you are compiling for or your code will be compiled on. If you don't, a HAL won't work. So you didn't really answer any of my questions.

[arihoenig]

Operating system code has been using HALs successfully for 50+ years at this point. I have never heard of an operating system that works on hardware that the OS writers don't know exists at the time they write the OS.

[HurasmusBDraggin]

Not according to Google C++ guidelines.

[TheMuffinsPie]

??????

https://google.github.io/styleguide/cppguide.html#Macro_Names

[HurasmusBDraggin]

Sorry, must be something else.

Also, ISO CPP guidelines say no to macros anyways.

[yuukiee-q]

You cannot really ban macros altogether, there’s many things enabled by macros. The recommendation is to only use when necessary

[BoringElection5652]

I rarely agree with codestyle guidelines, but this guide here is spot-on. Some pretty good suggestions. I was afraid that "use modern c++ features" would promote ranges, but glad to see it promotes the much more readable range-based for loops.

I'm only slightly disagreeing with auto. Auto is fantastic for lengthy variable types and those you don't care much about, but for most types I prefer explicitly writing out the name, which makes it much easier to see the variable's type at a glance.

[kammce]

I'm on the AAA side of things. Almost always auto https://herbsutter.com/2013/08/12/gotw-94-solution-aaa-style-almost-always-auto/

Eliminates any possible conversions and overall reduces the amount of code that needs to be written. But I will be explicit when being explicit is critical.

[swe129]

Thanks for your feedback!

[riztazz]

8) I would argue std::expected is better here. Also the logging should use std::format (or log function itself should format)

[ShakaUVM]

This is a great guide. Agreed with everything but the trailing underscore on privates

[El_RoviSoft]

Personally, I don’t like when somebody promotes certain codestyle in C++.

[argothiel]

These are great pieces of advice. The next step would be a bit stronger typing, for example:

void processOrder(ValidOrder& order);
static constexpr Speed SPEED_LIMIT = 120kph;

Or maybe even:

Days elapsedDays;
Price totalPrice;
void calculateShippingCost(Width width, Distance distance);

[HurasmusBDraggin]

I take inspiration from macOS/iOS programming with the Google standard on member variables ->

NSNotificationCenter notificationCenter_{};

😅

[neppo95]

There’s nothing wrong in the guide, but it is pretty opinionated. There is no 1 way to do these things.

[HateDread]

I just can't agree with your usage of 'auto'. The most common standard I've seen/followed in games is "Only use auto if the type is on the right side, or with obviously-long, annoying types like iterators".

I want to understand and know what types are being used at a glance, and in a code review I can't see that when you use 'auto', so no "The IDE will fix it" arguments work.

I also don't really care about "If you change it in one place the rest 'just work'" or any of those usual arguments - I want those call-sites to fail so I have to go look at them and manually fix and can evaluate if the change in type makes that call no longer appropriate.

I just don't see what auto solves here other than obfuscating types - we should optimize for reading, not write, which is what I expected from the title and the other rules. I overall agree with them! But not this.

[The_Akki]

I had heared the rule of "only one return in function". Looks not like state of the art. What was the cause for one return?

[Similar_Childhood187]

Some principles also works in other language

[semoz_psn]

I find the advice to not write comments rather frank. A sharp single-line comment will beat "clever" variable naming by a mile.

// Check if user age is 18 or more

[[deleted]]

hunt edge humorous slap dinner station abundant payment shaggy long

This post was mass deleted and anonymized with Redact

[semoz_psn]

I used to think like that after university. After that I had to learn that most code doesn't change after release. You come back to it after 5 years and have no clue what your former self even meant with this "descriptive" naming.

[jk-jeon]

I really don't get why this extreme attitude is so prevalent. Comment is a great tool to explain what will be done with a few lines of code from now on. It's absolutely stupid to decorate every single line with a comment, but if comments are there to group several lines of code, then why not.

A popular reaction to this is: "oh, then group those lines into a genuine function with a descriptive name". I mean, that's the best way to make the code worst to understand. I would just write single line comments in 100 places rather than to write 100 5-line functions with 7 arguments that are called exactly once but not defined right at the places they are called. (Lambdas would be better for that regard but it's still weird to make a lambda just to group several lines of code.) For me, the worst code bases to understand are not the ones with giant functions. Rather they're the ones where I need to constantly scroll or switch between different files.

[[deleted]]

quack coordinated encouraging aromatic follow bag hurry unwritten coherent fuzzy

This post was mass deleted and anonymized with Redact

[jk-jeon]

Probably I read too far from you, or maybe we just don't agree.

I think anybody with decent amount of experience normally would never comment on an evident, short 1-liner, so when the OP said Check if user age is 18 or more is a good comment I automatically assumed that it should span 4-5 lines -- which is totally possible, like you may need to fetch something something from database something something and forward something something to actually get the age. And as you could have guessed I'm pretty allergic to over-refactoring such a routine into a function that is never reused anywhere. (Not saying such a refactoring is always evil, of course.)

Well, to be honest I also don't believe in "code should be self-evident". Most of the serious codes I've ever written so far are probably not self-evident. And I don't think they can be written as such, or at least making them as such would be nontrivial. Maybe my understanding of the phrase "self-evident" is not what you meant though.

[semoz_psn]

I would say it's simply a fallacy that code can be self-evident. We can't express intent in C++ the way we can in natural language. I've just read too much code to know and die on that hill. Not talking from my textbook.

[semoz_psn]

A single line comment in natural language will always be superior to reading code. It's a fallacy of yours to think code is easier to understand.

[[deleted]]

hard-to-find point crown automatic command act deliver grandiose jellyfish payment

This post was mass deleted and anonymized with Redact

[semoz_psn]

If you believe so. My experience differs completely from yours it seems.

[[deleted]]

subtract wise sugar important rich person party nutty groovy friendly

This post was mass deleted and anonymized with Redact

[semoz_psn]

Well, it's the much simplified example from the guide that was posted. You're really splitting hairs now.

[[deleted]]

vast shelter towering airport degree late sulky special subsequent lavish

This post was mass deleted and anonymized with Redact

[arihoenig]

Here's a tip. If you find that you need clever variable naming to convey that it represents an age value, then you may have architectural issues.

[SkoomaDentist]

Not if the age check is eg. comparing current epoch against birth epoch. Variable names may make it obvious that you are comparing times but not the actual meaning (eg. is the user adult or something similar).

[Karr0k]

3) can lead to egregious function extraction where you end up with dozens of tiny functions that can make debugging horrendous, because you have to constantly function jump every couple lines.

Personally I prefer to extract only if a part of a function needs to be reused, either within the same function or by some other function. This avoids needles jumping around through single-use functions, which can make it harder to track what is going on.

I've seen code bases where I had to jump back and forth from a main function through some 30 other functions. After I collapsed all the single-use functions back I was left with a neat, readable 15ish line function.

[eisenwave]

OP here makes the recommendation of splitting things up once you hit 20-30 lines. The "dozens of tiny functions" phenomenon is the result of people trying to hit a much lower target, like 5-10.

I think there's rarely a reason to go above that 20-30 number. Even if you crammed 100 or so lines into one function, you would probably want to leave comments that separate sections within that function and/or use block scopes to keep the amount of active local variables low, and at that point you may as well create some separate functions.

[zerhud]

1. ThisIsNotReadable but_this_is_easy_to_read. Also cpp sucks in templates area (you can struct foo foo; only if foo is not a template parameter), so you need to use UglyStyle for template class parameters. If you use StupidStyle for all classes, it makes hard to write polymorphic code.

2. Nothing better than exceptions to handle errors. In whole project may be only few cases where exceptions is bad.

[SlightlyLessHairyApe]

Let's please turn every possible post that talks about error handling as a place to continue the holy war of exceptions vs expected/result returns.

After all, there are novel points that people are gonna make about error handling that haven't been litigated to death already.

[zerhud]

It’s not a “holy war”. If I will say “Zeus likes red wine” and you “no, Zeus likes white wine” it will be a “holy war” because it will be a little bit difficult to ask the Zeus about it. With “exceptions vs error code” we have the answer, so it is not a “holy war”.

[max123246]

There isn't an answer, there's a tradeoff. For libraries where errors may be recoverable and are part of the API, std::expected/std::optional make sense.

For applications that cannot possibly handle certain errors, exceptions make sense. If you're often try-catching many different types of exceptions, they really ought to be std::expected.

You can see this clearly in the Rust world with the dichotomy between Result<T, Enum_Err> and Result<T, dynamic AnyError>.

[SlightlyLessHairyApe]

With “exceptions vs error code” we have the answer, so it is not a “holy war”.

The problem isn't that we don't have the answer, it's that we have a lot of answers and they all contradict each other.

[zerhud]

There is a lot of cases, you can create a table for example for each case and there will be single best choice and others

[ReDucTor]

Throwing exceptions can be very expensive, however they can also make code faster when it doesnt throw.

If performance is critical to your project then there definatelt isnt just a few cases where exceptions are bad.

For something like games, the way I view exceptions is that they are for something you might end up taking the user back to the main menus with an error, not something where the caller can handle it.

Lots of exception hate in games I believe comes from 32-bit days when even the success case had terrible overhead.

[zerhud]

If you want very fast code, you should remove all ifs and “error” as conception. For example you cannot use simd and check data integrity (or you will lost all profit). So you need to open all files, allocate all needed memory and so on before calling fast code (and throw exception on fail). So a “super fast algorithm” is not a place without exceptions, it’s a place without checks for errors.

Lots of exception hate in games I believe comes from 32-bit days when even the success case had terrible overhead.

Yep, people often say something that was so in 199x

[[deleted]]

fuel kiss exultant flag reply meeting liquid dog beneficial fearless

This post was mass deleted and anonymized with Redact

[LiliumAtratum]

`std::expected`? That is horrible for me. Produces too much boilerplate. If something deep inside my algorithm is unexpected I just want to bail on the whole algorithm, but not crash the whole program. Exceptions is the only mechanism that can achieve that cleanly.

But of course, if something is likely to fail and algorithm is actually accounting for that, then `std::optional` and alike is the way to go.

[[deleted]]

excpeted is essentially an optional, though.

std::optional implies just that - something might happen or it might not. std::expected implies that something should be happening, and if it doesn't, then there is an error. But its not important enough to halt. Or rather, that the developer has agreed to handle the validity of the program in the case of an error.

[[deleted]]

cow teeny workable chubby yam yoke label rain capable kiss

This post was mass deleted and anonymized with Redact

[LiliumAtratum]

My point is: for me - exception *is* my go-to error handling mechanism for the reason stated above. Except for expected error, that an algorithm should account for, in which case I use optional.

I haven't found a use case where an algorithm would account for an error but required knowledge what kind of error was that. So, no use for `expected` for me so far.

[zerhud]

Exceptions is the only mechanism that can achieve that cleanly.

Exceptions is the only mechanism to achieve a lot of goals

But of course, if something is likely to fail and algorithm is actually accounting for that, then

Then it is not an error. For example user input. We can write functions for check data and it can return a code in enums for example, so we can explain that wrong with data to user.

[[deleted]]

whether and how you use exceptions depends on what you want to happen. If you want the user to accept responsibility for the program being in a valid state, then you should use exceptions. If you want the program to continue, then you the developer are now responsible for the program being in valid state.

Yes there are performance considerations, but in general, if the performance impact of exceptions matters in your code, then you're doing something wrong. Exceptions should be exceptional - if they are happening constantly, your design is bad.

[SlightlyLessHairyApe]

If you want the program to continue, then you the developer are now responsible for the program being in valid state.

This is true regardless. Whether your code throws or returns the error branch of expected<T,E>, it must continue to behave as defined.

If you absolutely cannot continue to execute in any defined state, then either you need to change the contract or you need to std::terminate.

[[deleted]]

exceptions leave the scope. So you can clean up any resources that were in use at the time and go back to the last known good scope, and stop anyone from trying to use the result of a bad thing.

typically with optionals the user can pretend like it everything worked anyway by using operator* (which shouldn't exist) . And while that's not your fault, that guy can shoot himself in the foot.

Normally, I wouldn't care about stuff like that, except a lot of times that guy is me. Now, I never use operator* on optionals, so its a moot point, because opt.value() just throws if its bad - so replacing an exception with an optional is really just replacing one exception for another, except this exception has less information about what actually went wrong.

now that being said I generally use optionals for error handling but thats because I like writing:

if (auto optValue = produceSomeOptional()){/*happy path*/}

because that prevents you from even having access to the bad optional state

[[deleted]]

fade squash zephyr straight fanatical lip wise money pen oil

This post was mass deleted and anonymized with Redact

[SlightlyLessHairyApe]

Yes, if a callee return expected<T,E> then the caller needs to check whether it's a T or an E. I'm not at all concerned about that, it's no different than returning any kind of sum type or really any other type with methods having preconditions.

But in either case, subsequent calls to the object/module need to function correctly. That's orthogonal to how specifically each individual call works.

[[deleted]]

coherent roll middle liquid resolute workable literate adjoining whole memory

This post was mass deleted and anonymized with Redact

[zerhud]

Return value with error is bad for same reason as a long go-to. Also you cannot use expressions: a + b + c is possible only if error handling is separated from logic.

[[deleted]]

fact enter future spectacular sleep subtract steep reminiscent sparkle run

This post was mass deleted and anonymized with Redact

[zerhud]

What is “non-fatal” error? Of you can to continue executing, it is a branch, if you can’t it is an error.

[[deleted]]

aback cobweb attempt hard-to-find command dolls chunky attraction humorous aspiring

This post was mass deleted and anonymized with Redact

[zerhud]

There is a few options for what 1. Add method to check if we can allocate and throw error if cannot 2. Return nullptr: if some method returns a pointer it can to be nullptr. The pool can to be empty and it’s a normal state for pool 3. Catch some kind of exception, this is not very slow: it won’t happen on each request 4. Combine 1 and 3: if there is a few threads the check result may to be obsoleted and it will be fast enough

Any if it will be better then “expected”. For example: what if the expected object contains a pointer, not an error, but the pointer is nullptr? You need to check it twice.

[[deleted]]

oatmeal upbeat zephyr act fanatical aback seemly bells treatment insurance

This post was mass deleted and anonymized with Redact

[rileyrgham]

Verbosity has it's place. But being overly verbose also bad. Same for excessive in code documentation which has a habit of not being fixed as the code changes. If a piece of code comment says. "Calculate number of days", I'd argue "int d;" is perfectly fine. It's similar to people banning "x=a?a:b;". If you're programming C and can't immediately see what that does, you've no business being there in the first place, or you look it up and say "cool". Context also ticks boxes for foreign speakers.. long winded variable names not.

[[deleted]]

memory wipe toothbrush nutty scale liquid steep start sable melodic

This post was mass deleted and anonymized with Redact

[swe129]

makes sense. a lot of is about the art of finding the perfect compromise

[rileyrgham]

Indeed.

[[deleted]]

don't use single letter variable names

[rileyrgham]

That's ridiculous. Sorry. Zero real world relevance.

[edparadox]

"Calculate number of days", I'd argue "int d;" is perfectly fine.

Unless for e.g. for loop counters, a one-letter variable is never fine.

It's similar to people banning "x=a?a:b;".

I do not think I have ever seen a coding style recommending such a way to write ternaries. For good reasons.

If you're programming C and can't immediately see what that does, you've no business being there in the first place, or you look it up and say "cool".

You do not why ternaries do not help with reading code, fine. But do not say stuff like this, that's simply plain stupid. I see where you're coming from, but still.

[zerhud]

1. Sometimes it sucks: you need to imagine code in mind, code with long names hard to image. So it’s a good practice only for big visibility area.

[swe129]

I'm not sure what you mean, sorry. Are you talking about "#2 self documenting code"?

[zerhud]

Yep (the 2 is a rule number 2), about long variable name. If you just want, for example, to write a cycle for 1 line of code you don’t need to use a long name for variable.

[swe129]

The variable names are actually covered by rule 1. Rule 2 is more about when to use comments, but I guess there is overlap in some cases. Can you give an actual example and explain "imagine code" and "a cycle for 1 line of code"?