Coding Horrors: You can gather all your technical debt into one easy framework!

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > The Cavern of COBOL > Coding Horrors: You can gather all your technical debt into one easy framework!

«‹›1503 »

Malcolm XML: Aug 8, 2009; I always knew it would end like ｔｈｉｓ．

pokeyman posted:

I always thought "self-documenting code" was just an unattainable ideal. A faux-erudite version of "try to code good".

I guess tests are superior to a smattering of comments buried in lengthy, closed pull requests. I'm not sure that elevates them to the level of "effective documentation".

self documenting code is impossible, you always need comments, tests are not documentation (are u gonna release ur testsuite?), you need both examples and text

hth

# ? Oct 14, 2014 16:55

Adbot: ADBOT LOVES YOU

# ? May 17, 2024 15:10

more like dICK: Feb 15, 2010; This is inevitable.

The obvious solution is literate programming :getin:

# ? Oct 14, 2014 17:02

Zombywuf: Mar 29, 2008

Blotto Skorzany posted:

Well for one thing, because function pointers and function objects are not functors

Wikipedia disagrees https://en.wikipedia.org/wiki/Functor_(disambiguation)

# ? Oct 14, 2014 17:49

qntm: Jun 17, 2009

good jovi posted:

You're a crazy person, and here's eight pages detailing why.

How ironic.

# ? Oct 14, 2014 18:02

Volmarias: Dec 31, 2002; EMAIL... THE INTERNET... SEARCH ENGINES...

Malcolm XML posted:

(are u gonna release ur testsuite?)

If you're releasing the source as well then yes, absolutely.

# ? Oct 14, 2014 18:49

Harik: Sep 9, 2001; From the hard streets of Moscow
First dog to touch the stars; Plaster Town Cop

The easiest way to tell if something needs a comment: a few weeks later you're back in that part, tracking down a different bug. If you have to take time to figure out what the code is doing, do everyone a favor and leave an explanation. If you're right, so much the better. If you're wrong, it really needed an explanation when it was written.

Bit of a self-horror here. I've got a class called "Legacy". It's basically a direct copy of all the business logic of a tiny embedded part migrated over to the native portion of an android system.

All of the logic: a gigantic god-class singleton that still has remnants of it's former character-based LCD origins dangling on what I can only hope are dead code paths. I've been carving bits of it off, slowly, but the main problem with it is that it works the way the customer wants with a very murky set of requirements that basically boil down to "The way I expect it to."

# ? Oct 14, 2014 19:00

FlapYoJacks: Feb 12, 2009

pigdog posted:

That's actually one of the reasons why comments get out of date so easily. Suppose you do code in a team; a junior programmer can change the code to fix a bug or something, but do they also know the system well enough to update the comments in all the relevant places?

The relevant place should be near the line of code or on the top of the function. If you are too lazy to add or modify a comment that says something like:

/* This code fixed this bug: ${BUG} */

Then I don't want to code with you because you are lazy and don't have decent coding habits, and yes; documentation IS part of good coding habits.

FlapYoJacks fucked around with this message at 22:03 on Oct 14, 2014

# ? Oct 14, 2014 21:56

Soricidus: Oct 21, 2010; freedom-hating statist shill

I love the argument that comments might get out of date so you should just abandon them and use descriptive method names instead. Because there's no way anyone would ever change a method without updating its name ... right?

Missing method comments are a code smell. It might still be good code, but it's often a sign of sloppy maintenance.

# ? Oct 14, 2014 22:01

baquerd: Jul 2, 2007; by FactsAreUseless

ratbert90 posted:

The relevant place should be near the line of code or on the top of the function. If you are too lazy to add or modify a comment that says something like:

/* This code fixed this bug: ${BUG} */

No, this is crap. I don't want my code littered with comments like that, it actually makes things much harder to understand. Version control commit messages that link to Jira stories will allow me to dig deep if I want.

For internal code, public interfaces need comments on a per-method basis, everything else can have class level or no comments at all. Class names and unit tests with good names tell me what a class should do, a modern IDE allows me to quickly find method callers and view project structure and flow, and then there's that pink stuff in my head that works pretty well at figuring stuff out as well.

# ? Oct 14, 2014 22:11

NFX: Jun 2, 2008; Fun Shoe

ratbert90 posted:

The relevant place should be near the line of code or on the top of the function. If you are too lazy to add or modify a comment that says something like:

/* This code fixed this bug: ${BUG} */

Then I don't want to code with you because you are lazy and don't have decent coding habits, and yes; documentation IS part of good coding habits.

Comments are cool, but in 5 years noone is going to care that ${BUG} existed, they'll just look at the code and think duh:

code:

float CalculateSpan(float a, float b)
{
  float span = b - a;

  // abs is needed to fix ${BUG}: "some arguments result in span being negative".
  return fabs(span);
}

# ? Oct 14, 2014 22:12

FlapYoJacks: Feb 12, 2009

baquerd posted:

No, this is crap. I don't want my code littered with comments like that, it actually makes things much harder to understand. Version control commit messages that link to Jira stories will allow me to dig deep if I want.

For internal code, public interfaces need comments on a per-method basis, everything else can have class level or no comments at all. Class names and unit tests with good names tell me what a class should do, a modern IDE allows me to quickly find method callers and view project structure and flow, and then there's that pink stuff in my head that works pretty well at figuring stuff out as well.

No poo poo they do, that's why I said PART of good coding habits. The work I do requires comments, because sorry but:

C code:

int do_stuff(void)
{
   unsigned int base = CCM_BASE;
   unsigned int offset = 0x40;
   void __iomem *ss_base = NULL;
   unsigned int val = 0x0bb88006;
   ss_base =  MX6_IO_ADDRESS(base);
   writel(val, ss_base  + offset );	
}

Is difficult to read. And other than base and offset which is under our control, all the other variables come from other peoples code.
I would much rather take the time to add a few comments to make it understandable.

# ? Oct 14, 2014 22:18

Che Delilas: Nov 23, 2009; FREE TIBET WEED

Does the HTML for the last 10 pages of this thread count as "code?"

Just wondering.

# ? Oct 14, 2014 22:33

Master_Odin: Apr 15, 2010; My spear never misses its mark...

ladies

I've had to fix some code that the comments said one thing but the function does something else (and the comments in this case were actually right). The code was missing tests to ensure this functionality from the comments. But I'm glad the comments were there or else maybe they wouldn't be fixed!

ratbert90 posted:

The relevant place should be near the line of code or on the top of the function. If you are too lazy to add or modify a comment that says something like:

/* This code fixed this bug: ${BUG} */

Then I don't want to code with you because you are lazy and don't have decent coding habits, and yes; documentation IS part of good coding habits.

I would say that this is only useful for ignoring tests or something (where you link to a JIRA story and say why it's ignored, in case the project moves on JIRA and loses its old stories) as otherwise all the relevant information on how a file was changed is the point of the CVS.

Unless maybe you had to do something convoluted to fix a bug that is really non-obvious maybe? Otherwise I'd think more general purpose comments just explaining what something does is better.

# ? Oct 14, 2014 22:37

Dessert Rose: May 17, 2004; awoken in control of a lucid deep dream...

TheresaJayne posted:

and this is WIP for a game i was working on but has now hit the doldrums
https://github.com/theresajayne/tranquility

I got bored after looking through like fifteen classes and only seeing boilerplate getters/setters. Is there any actual code in here? What did you even write besides the DB schema?

I guess that

code:

public class UniverseVO extends ValueObject {
private Long universeID;
private String universeName;
public Long getUniverseID() {
return universeID;
}
public void setUniverseID(Long universeID) {
this.universeID = universeID;
}
public String getUniverseName() {
return universeName;
}
public void setUniverseName(String universeName) {
this.universeName = universeName;
}
}

is "self-documenting" in that it doesn't do anything and so I don't need any documentation to tell me what it's not doing?

I mean there are seriously four levels of abstract interface and implementations in here. It reads like one of those "Java is bad lol" jokes.

# ? Oct 14, 2014 22:38

FlapYoJacks: Feb 12, 2009

Master_Odin posted:

I've had to fix some code that the comments said one thing but the function does something else (and the comments in this case were actually right). The code was missing tests to ensure this functionality from the comments. But I'm glad the comments were there or else maybe they wouldn't be fixed!

I would say that this is only useful for ignoring tests or something (where you link to a JIRA story and say why it's ignored, in case the project moves on JIRA and loses its old stories) as otherwise all the relevant information on how a file was changed is the point of the CVS.

Unless maybe you had to do something convoluted to fix a bug that is really non-obvious maybe? Otherwise I'd think more general purpose comments just explaining what something does is better.

Ok, I can reword my thoughts.

If you are too lazy to add a small blurb as to what the code does, I don't want to work with you.

C++ code:

	/* Check to see if cloud has butt and run Do_Function to prevent
	   problems that could be caused by cloud having butt in the string.  */
	if (strstr(dev->cloud, "butt"))
	{
	  Do_function();
	}

# ? Oct 14, 2014 22:39

itskage: Aug 26, 2003

NFX posted:

Comments are cool, but in 5 years noone is going to care that ${BUG} existed, they'll just look at the code and think duh:
code:
float CalculateSpan(float a, float b)
{
  float span = b - a;

  // abs is needed to fix ${BUG}: "some arguments result in span being negative".
  return fabs(span);
}

Yeah whenever our ISV worked on stuff for us we'd get notations like that in the code for bug fixed and enhancements, but then as more bug fixes or enhancements were added it just becomes a mess.

Like so:

code:

// Calculates the span between two numbers per ${MOD} on ${Date} by ${Vendor}
float CalculateSpan(float a, float b)
{
  // Fixed misspelled variable name from "spin" to "span" per ${BUG} on ${Date} by ${Vendor} 
  float span = b - a;

  // abs is needed because some arguments result in span being negative per ${BUG} on ${Date} by ${Vendor}
  // Original: return span;
  return fabs(span);
  
  // End of ${Vendor} change
}

Or something like that. But as you can see it becomes a loving nightmare of comments that don't take advantage of the VCS and don't even matter if you just read the code. Their bad examples rubbed off on the internal devs and so I had to do a whole drat pow wow and explain the problem with this and why even through they are the 'expert's that this is stupid and wrong, and then I had them go through and strip out or combine a lot of this poo poo.

# ? Oct 14, 2014 22:51

astr0man: Feb 21, 2007; hollyeo deuroga

ratbert90 posted:

Ok, I can reword my thoughts.

If you are too lazy to add a small blurb as to what the code does, I don't want to work with you.

If it's obvious what your code is doing it doesn't need comments. In this case if your function was named handle_butts() or something it wouldn't need any additional explanation.

# ? Oct 15, 2014 01:58

ErIog: Jul 11, 2001

astr0man posted:

If it's obvious what your code is doing it doesn't need comments. In this case if your function was named handle_butts() or something it wouldn't need any additional explanation.

This is why I name all of my functions like "handle_butts_returns_false_if_butthandle_invalid_true_if_butthandling_successful_takes_single_butthandler_or_array_of_butthandles(ButtHandle butthandle = false, Array butthandles = [])"

The comment isn't there to tell you what the function does necessarily. It's there to tell you why the function exists and appropriate usage details. Not all of that information can fit in a function name.

ErIog fucked around with this message at 02:06 on Oct 15, 2014

# ? Oct 15, 2014 02:03

JawnV6: Jul 4, 2004; So hot ...

Go to JS compiler

The real horror is trying to appeal to the Gopher crowd. Get with the times, Go OTG, Gode, GS, all aim for that younger demo. Or is that the point?

# ? Oct 15, 2014 02:18

Xenoveritas: May 9, 2010; Dinosaur Gum

ErIog posted:

This is why I name all of my functions like "handle_butts_returns_false_if_butthandle_invalid_true_if_butthandling_successful_takes_single_butthandler_or_array_of_butthandles(ButtHandle butthandle = false, Array butthandles = [])"

So you're the one who designed the Mac OS X API.

# ? Oct 15, 2014 02:24

hobbesmaster: Jan 28, 2008

ratbert90 posted:

Ok, I can reword my thoughts.

If you are too lazy to add a small blurb as to what the code does, I don't want to work with you.
C++ code:
	/* Check to see if cloud has butt and run Do_Function to prevent
	   problems that could be caused by cloud having butt in the string.  */
	if (strstr(dev->cloud, "butt"))
	{
	  Do_function();
	}

The comment there just restates the code. The comment there should explain why that check is necessary.

# ? Oct 15, 2014 02:25

astr0man: Feb 21, 2007; hollyeo deuroga

ErIog posted:

The comment isn't there to tell you what the function does necessarily. It's there to tell you why the function exists and appropriate usage details. Not all of that information can fit in a function name.

Yeah I understand that, but his example was an if statement and a function call, along with a comment that said "check this condition and then call function()". Comments like that are wasted space and don't do explain anything that isn't already obvious to anyone reading the code.

# ? Oct 15, 2014 02:25

baquerd: Jul 2, 2007; by FactsAreUseless

ratbert90 posted:

No poo poo they do, that's why I said PART of good coding habits. The work I do requires comments, because sorry but:
C code:
int do_stuff(void)
{
   unsigned int base = CCM_BASE;
   unsigned int offset = 0x40;
   void __iomem *ss_base = NULL;
   unsigned int val = 0x0bb88006;
   ss_base =  MX6_IO_ADDRESS(base);
   writel(val, ss_base  + offset );	
}
Is difficult to read. And other than base and offset which is under our control, all the other variables come from other peoples code.
I would much rather take the time to add a few comments to make it understandable.

OK, yeah, the closer you're working to assembly the more comments are required. Working in a higher level language like Java, C#, Ruby, Python, et al. allows you to choose variable names that aren't complete poo poo though.

# ? Oct 15, 2014 03:09

Subjunctive: Sep 12, 2006; ✨sparkle and shine✨

val not being a manifest constant is a paddling, though. And ss_base better have some clear meaning in your context. :colbert:

# ? Oct 15, 2014 04:16

FlapYoJacks: Feb 12, 2009

Subjunctive posted:

val not being a manifest constant is a paddling, though. And ss_base better have some clear meaning in your context.

It does indeed. Spread Spectrum :colbert:

# ? Oct 15, 2014 04:23

Dessert Rose: May 17, 2004; awoken in control of a lucid deep dream...

baquerd posted:

OK, yeah, the closer you're working to assembly the more comments are required. Working in a higher level language like Java, C#, Ruby, Python, et al. allows you to choose variable names that aren't complete poo poo though.

What prevents you from using a variable name that isn't complete poo poo in C?

# ? Oct 15, 2014 04:28

HFX: Nov 29, 2004

baquerd posted:

OK, yeah, the closer you're working to assembly the more comments are required. Working in a higher level language like Java, C#, Ruby, Python, et al. allows you to choose variable names that aren't complete poo poo though.

It is too bad that C comes from a time where everything was at a premium. A lot of the terseness is left over from those days. Sadly, old programmers and new programmers working with old code like to carry on bad traditions even when they are not needed anymore. It is often hard to break them that habit. I speak that from experience.

Best rule of comments is to use them for covering pointing out the corner cases, side effects, and other non obvious items. That said I would say 90% of the comments I run across are useless, and when I need them the most, they are non existent.

HFX fucked around with this message at 04:44 on Oct 15, 2014

# ? Oct 15, 2014 04:32

baquerd: Jul 2, 2007; by FactsAreUseless

Dessert Rose posted:

What prevents you from using a variable name that isn't complete poo poo in C?

In addition to what HFX said, sometimes you're doing something like pointer arithmetic to hack in solutions that just need a good bit of explanation to make sense. I'm not really a C guy though, I just know that it seems to universally have crap variable names.

# ? Oct 15, 2014 04:36

Steve French: Sep 8, 2003

baquerd posted:

[Ruby, Python] allows you to choose variable names that aren't complete poo poo though.

Not so sure about this, especially if we are talking about code that is supposed to be self documenting.

# ? Oct 15, 2014 04:36

Subjunctive: Sep 12, 2006; ✨sparkle and shine✨

Comments within a function are mostly used well to say "before you read this next part, let me explain to you that I'm not actually a terrible developer; I had no choice, because..." or "please refer to this extensive external documentation of this algorithm".

# ? Oct 15, 2014 04:56

FlapYoJacks: Feb 12, 2009

Dessert Rose posted:

What prevents you from using a variable name that isn't complete poo poo in C?

Nothing, it's just memory at the end of the day, and I generally do use descriptive variable names and function names, but trolling around kernel code can become tedious a lot of times when other people don't, so I always put a header at the top of every function I write just so I don't become the person I hate.

# ? Oct 15, 2014 04:58

Subjunctive: Sep 12, 2006; ✨sparkle and shine✨

ratbert90 posted:

trolling around kernel code can become tedious

People who use the word "kernel" outside of actual privileged-operating-system-code are usually trying to excuse cleverness that doesn't pay for itself, or otherwise indulge their illusions of Kernighan-ness. Beware.

Even within privileged OS code, it's used to paper over a lot of terrible shortcuts ignoring that humans will someday read this text.

# ? Oct 15, 2014 05:03

FlapYoJacks: Feb 12, 2009

Subjunctive posted:

People who use the word "kernel" outside of actual privileged-operating-system-code are usually trying to excuse cleverness that doesn't pay for itself, or otherwise indulge their illusions of Kernighan-ness. Beware.

Even within privileged OS code, it's used to paper over a lot of terrible shortcuts ignoring that humans will someday read this text.

Oh I mean Linux kernel level code. :v:

Ask me about Macros that go to Macros that combine into their own separate functions!

# ? Oct 15, 2014 05:19

Subjunctive: Sep 12, 2006; ✨sparkle and shine✨

ratbert90 posted:

Oh I mean Linux kernel level code. Ask me about Macros that go to Macros that combine into their own separate functions!

Yeah, I did Linux filesystem work for a few years, and other misc network/porting stuff before that. It's a sewer of "you must not be smart enough" treehouse programming.

# ? Oct 15, 2014 05:54

Hughlander: May 11, 2005

Dessert Rose posted:

What prevents you from using a variable name that isn't complete poo poo in C?

The last time I was paid to write C the compiler wouldn't complain about, but would ignore any part of an identifier after 8 letters.

# ? Oct 15, 2014 06:06

FlapYoJacks: Feb 12, 2009

Hughlander posted:

The last time I was paid to write C the compiler wouldn't complain about, but would ignore any part of an identifier after 8 letters.

Wow, that compiler must have been horribly lovely.

Subjunctive posted:

Yeah, I did Linux filesystem work for a few years, and other misc network/porting stuff before that. It's a sewer of "you must not be smart enough" treehouse programming.

But it's posix compliant so it must be good! :downs:

FlapYoJacks fucked around with this message at 06:26 on Oct 15, 2014

# ? Oct 15, 2014 06:23

Coffee Mugshot: Jun 26, 2010; by Lowtax

Dessert Rose posted:

What prevents you from using a variable name that isn't complete poo poo in C?

Writing a C compiler

# ? Oct 15, 2014 06:27

Suspicious Dish: Sep 24, 2011; 2020 is the year of linux on the desktop, bro; Fun Shoe

Progressive JPEG posted:

I think of comments as justification for why a given piece of code needs to exist, and of commit messages as justification for why that code needs to be changed. Otherwise why does it need to exist?

It doesn't. Stop writing code.

# ? Oct 15, 2014 06:36

Progressive JPEG: Feb 19, 2003

Suspicious Dish posted:

It doesn't. Stop writing code.

Welcome to management

# ? Oct 15, 2014 06:45

Adbot: ADBOT LOVES YOU

# ? May 17, 2024 15:10

TheresaJayne: Jul 1, 2011

Dessert Rose posted:

I got bored after looking through like fifteen classes and only seeing boilerplate getters/setters. Is there any actual code in here? What did you even write besides the DB schema?

I guess that
code:
public class UniverseVO extends ValueObject {
private Long universeID;
private String universeName;
public Long getUniverseID() {
return universeID;
}
public void setUniverseID(Long universeID) {
this.universeID = universeID;
}
public String getUniverseName() {
return universeName;
}
public void setUniverseName(String universeName) {
this.universeName = universeName;
}
}
is "self-documenting" in that it doesn't do anything and so I don't need any documentation to tell me what it's not doing?

I mean there are seriously four levels of abstract interface and implementations in here. It reads like one of those "Java is bad lol" jokes.

As i said i got bored, all the boilerplate really got me down

i like code that does stuff not just sets up stuff, also that was a few years ago (moved it from sourceforge to github a while back as well.
and it was based on the coding standard and design as used by Perform Group where i used to work.

# ? Oct 15, 2014 07:04

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > The Cavern of COBOL > Coding Horrors: You can gather all your technical debt into one easy framework!

«‹›1503 »