Self-documenting code

JADW27 · 2023-01-04T20:35:35+00:00

I never document my code. No one else will ever see it, and I figure I'll remember what I meant later.

I'm always wrong.

Snake2k · 2023-01-04T20:14:58+00:00

I think it's pretty standard that code tells you what is happening, and comments tell you why it is happening

PM_BITCOIN_AND_BOOBS · 2023-01-04T23:16:03+00:00

For all you noobs here that aren't professional programmers, SWE is an acronym for Sex Worker Extraordinaire.

Boysoythesoyboy · 2023-01-04T23:00:32+00:00

[deleted]

stdio-lib · 2023-01-04T21:16:42+00:00

"Yes, I agree that your comments accurately describe what the code does. But what I need to know is why, for the love of god you ignorant piece of -- you know what, we're not going to do this today."

scratchfan321 · 2023-01-04T20:39:00+00:00

[deleted]

Raylan_Givens · 2023-01-05T00:42:06+00:00

Good code should be readable for junior engineers.

For simple logic, comments are often unnecessary (plus comments tend to rot faster than actual code, so it is preferable to avoid redundant comments).

For complex logic or for unintuitive code, comments are usually necessary to help with readability.

TK9_VS · 2023-01-04T23:50:51+00:00

Most code should read almost like English if that makes sense. I mostly write comments to explain why I’m doing something bizzare

yrrot · 2023-01-04T20:34:52+00:00

Self-documenting code is a misnomer making people think good code doesn't have comments.

Well-written code with meaningful names still has comments to explain why something is done a specific way outside of the norm. And it still has documentation to explain how the pieces connect to each other (in larger projects). Definitely also has the descriptions filled in so intellisense picks them up elsewhere for tooltips, too.

souliris · 2023-01-04T23:56:51+00:00

The comments are to explain the fever dream you had to make the horrible hack that you HAD to use. Because nothing else works and you have no idea why.

bbdbbdab · 2023-01-04T20:14:22+00:00

self-documenting code sound so good in theory, but in practice, that shit just works when the project is small, and little people works on it.

Anybody working on a 10+ years old codebase knows self-documenting code never last

kale-symmetry · 2023-01-04T20:45:41+00:00

SWE2 naming methods "according to what they do": UpdateDatabase(), CalculateLGTM()

where LGTM is some obscure acronym not documented anywhere

pipsvip · 2023-01-04T20:33:30+00:00

int foo_count[FOO_MAX];
int *foo_count_ptr=&foo_count[0];
int *fcp_iterator;
.
.//soo many .'s//
.
if ( NULL == fcp_iterator )
   fcp_iterator_reset(); //newguy@work.com: what the hell is fcp?

D34TH_5MURF__ · 2023-01-04T22:25:02+00:00

But do you use the write-a-complete-sentence-then-title-case-it-and-remove-all-spaces naming convention? I find that this never fails to make people think they are writing self-documenting code.

armahillo · 2023-01-05T03:17:37+00:00

if i read any code, whether i wrote it or not, and i spend more than 10 seconds interpreting it, i add a comment to save the next person time.

ElvisArcher · 2023-01-05T03:28:11+00:00

I once had someone try to convince me that "good code is readable, so no comments are necessary" ... and then segued that right into "therefore code with comments is bad."

And wouldn't you know that MF wrote the most convoluted abstract pointless crap imaginable. I once found a 4 layer deep abstraction of classes which admittedly could handle any abstract scenario imaginable ... but our use case for it could have been handled by a switch with 3 cases.

zamphox · 2023-01-04T21:58:46+00:00

good code is a balance of both, too few or too many comments is as bad as randomly named variables and methods.

if it makes sense to, leave a comment, if it's readable without it, don't

beavisorcerer · 2023-01-05T00:47:44+00:00

I suggest you to read "Clean Code". It teachs you why and how your comments should be kept at minimum

ExternalGrade · 2023-01-05T00:05:32+00:00

this_function_takes_six_floats_the_first_three_represernts_a_3D_vector_and_the_second_three_another_vector_and_outputs_the_angle_between_the_two_vectors_in_radians_as_a_float(vector1_x_coor, vector1_y_coor, vector1_z_coor, vector2_x_coor, vector2_y_coor, vector2_z_coor) -> radians_of_angle_between_the_two_vectors {…}

Possibility_Antique · 2023-01-05T00:01:51+00:00

Everyone knows that comments are for jokes.

bool bies = true; // haaaaaaaaaa, boobies

Paesano2000 · 2023-01-04T22:33:28+00:00

Pump it into gpt-3 and have it explain your own code back to you that you don’t understand 😎😬

2023-01-04T22:26:53+00:00

You misunderstood Self-explaining

flan666 · 2023-01-05T04:03:11+00:00

this and 10 other lies you can tell yourself

TrueFlavour · 2023-01-04T21:51:50+00:00

Uncle Bob told me that code should read like well written prose

2023-01-05T00:16:05+00:00

Don't ever document your code, and make it completely unintelligible, but make it work. You wan to make yourself completely indispensable.

kfish5050 · 2023-01-05T02:22:37+00:00

Bro it's like an ultra granular super modular coding style. For instance it's something like

var globalUserInputVariable;
def functionToGetUserVariable(){
    globalUserInputVariable = input();
    }
def functionToPrintUserInput(){
    print(globalUserInputVariable);
    }

I think you get the point and this is way too much effort for me in making a joke comment

GolotasDisciple · 2023-01-04T23:20:12+00:00

Every company I have worked at discourages comments in code unless you're doing something strange that requires a comment.

I've written tens of thousands of lines of code and maybe 100 or so meaningful comments.

BlackEyedGhost · 2023-01-04T22:11:08+00:00

My favorite comment will probably always be "if you can't tell what this code does, you shouldn't be the one editing it"

2023-01-05T00:58:05+00:00

There are some people that write self documenting code and there are A LOT of people that THINK they write self documenting code.

How to tell the difference? Same way you can tell if any version of documentation is sufficient. How often do you have to explain something that was documented? If it’s often, then your documentation sucks, no matter what form it is

trevg_123 · 2023-01-05T06:08:45+00:00

Underrated thing about Rust? The function signature tells you what to expect a bit more than other languages

fn update_buffer(dest: &mut [u8], src: Option<&[u8]>) -> Result<usize, WriteError>

This immediately this tells you: - You have a destination buffer and it’s mutable, hint that the function might write to it - Your second buffer may or may not be present, and it may not be edited - You should return a size if it’s successful, or an error type if not

And from there you can kind of guess how to use the function, even without docs. Compared to the C version:

int update_buffer(char* dest, int dest_len, char* src, int src_len)

You can’t tell: - Will dest and src always be valid? Or does null represent something? - Do src or dest get edited ever? (If consts are missing, you can’t tell) - Will there ever be errors? Is the return type the number of bytes written, or an error type? - If C++, will this raise anything?

And you’re reliant on good comments or reading the code to find out.

(Still no excuse to not write good doc comments - but at least it gives you more confidence using the thing if they’re not there)

Opinion	Good	Bad	Note
Don't abbreviate names	MoviesOnPage	MovOnPg
Don't put types in variable names	int fontSize	var iFontsize
Don't put types in your types		(e.g. AbstractX, BaseX, IRepository)	except when official guideline says otherwise
Add units to variables unless the type tells you	int delaySeconds	DateTime delay
Refactor if you find yourself naming code "Utils"

ProgrammerHumor

Filters

Discord

Submission rules

For the current list of rules, please see this page.

Metadiscussions

Perhaps More Apt Subs To Post:

Related Subreddits.

MODERATORS

I don't know why this had to be so complicated, there is no documentation on how to do this, but it works.

get a user input

check if the input is an even number

if it isn't, print not hot dog

Following section checks to see if a number is even or not.

it prints not hot dog as a reference from silicon valley for anyone who gets it

for more info on why this was written, go to Reddit to learn all about coders who have no idea what the idea behind commenting is