terrible programmers: my god, it's full of chars

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > YOSPOS > terrible programmers: my god, it's full of chars

«‹›1446 »

oh no blimp issue: Feb 23, 2011

my code is documented by logging on the negative paths only
if you read them you know exactly what can go wrong but not why

# ? Nov 29, 2016 21:31

Adbot: ADBOT LOVES YOU

# ? May 25, 2024 22:57

Mao Zedong Thot: Oct 16, 2008

comments that get turned into documentation (javadoc, godoc, whatever c# has with them xml thingies, etc.) are good

pretty much all other comments are bad

sometimes you should use them -- but probably you should just write better, less clever code

# ? Nov 29, 2016 21:44

gonadic io: Feb 16, 2011; >>=

my boss isn't a fan of comments in general because we're so "agile" that he's worried they'll just be out of date (as they were when he inherited the codebase)

i try to slip them by him when doing non-obvious or counter-intuitive things.

i've also started crediting stack overflow in our (internal, propitiatory) codebase. i guarantee it's not the only SO code in there, but i at least make sure to attribute it (plus there'll usually be a discussion about why it's right there too)

# ? Nov 29, 2016 21:48

leper khan: Dec 28, 2010; Honest to god thinks Half Life 2 is a bad game. But at least he likes Monster Hunter.

gonadic io posted:

my boss isn't a fan of comments in general because we're so "agile" that he's worried they'll just be out of date (as they were when he inherited the codebase)

i try to slip them by him when doing non-obvious or counter-intuitive things.

i've also started crediting stack overflow in our (internal, propitiatory) codebase. i guarantee it's not the only SO code in there, but i at least make sure to attribute it (plus there'll usually be a discussion about why it's right there too)

jfc don't use CC-by-SA code

# ? Nov 29, 2016 21:54

Sapozhnik: Jan 2, 2005; Nap Ghost

Portions of this product contain code written by NiggerBlaster76, Aryan1488 et al.

# ? Nov 29, 2016 22:10

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

VOTE YES ON 69 posted:

comments that get turned into documentation (javadoc, godoc, whatever c# has with them xml thingies, etc.) are good

pretty much all other comments are bad

sometimes you should use them -- but probably you should just write better, less clever code

comments are useful where boilerplate gets in the way of reading the code. eg in c where all your actual function calls are buried in a heap of return value checks.

you do have to make sure they're kept up to date, but that's part of what code review is for.

# ? Nov 29, 2016 22:12

geeves: Sep 16, 2004

VOTE YES ON 69 posted:

comments that get turned into documentation (javadoc, godoc, whatever c# has with them xml thingies, etc.) are good

pretty much all other comments are bad

sometimes you should use them -- but probably you should just write better, less clever code

I wish some of my coworkers would learn streams and lambdas in Java instead of just adding comments to my code that says, "This loving works? I don't understand!"

# ? Nov 29, 2016 23:06

Mao Zedong Thot: Oct 16, 2008

all things in moderation, etc

# ? Nov 29, 2016 23:06

hackbunny: Jul 22, 2007; I haven't been on SA for years but the person who gave me my previous av as a joke felt guilty for doing so and decided to get me a non-shitty av

yes, jesus christ, if you copy a non-obvious snippet from somewhere, link to it. don't be my former coworker

# ? Nov 29, 2016 23:09

Elysiume: Aug 13, 2009; Alone, she fights.

comments you say? why take 0 lines when you can instead take ten. this is the only constructor defined

Java code:

 //---------------------------
 // Constructors
 //---------------------------
 
     /**
      * Constructor.
      */
     public ClassName() {
         // nothing
     }

bonus (this is the only member in the class)

Java code:

 //---------------------------
 // Class variables
 //---------------------------
 
     /** The logger for the class. */
     private static final Logger LOGGER = Logger.getLogger(ClassName.class);

# ? Nov 29, 2016 23:11

DONT THREAD ON ME: Oct 1, 2002; by Nyc_Tattoo; Floss Finder

my code is self mockumenting

# ? Nov 29, 2016 23:14

oh no blimp issue: Feb 23, 2011

Every comment in my code is just variations on
//why am i doing this?
//whats the point?
//we'll all die one day

# ? Nov 29, 2016 23:18

gonadic io: Feb 16, 2011; >>=

in the last crunch time we started getting comments like

// FIXME: this is horrific but gets us over the line
// TODO: write tests

but they're mostly gone now thank god. the remaining ones will be there for 10+ years though i'm sure

# ? Nov 29, 2016 23:20

jony neuemonic: Nov 13, 2009

Sapozhnik posted:

in my experience i always manage to extensively comment a piece of code ~7 days before it gets deleted

i just had to argue that yes, we should in fact delete code that was written for a feature we backed out of and never intend to finish or release.

i guess i can safely comment things. :toot:

# ? Nov 29, 2016 23:56

HappyHippo: Nov 19, 2003; Do you have an Air Miles Card?

VOTE YES ON 69 posted:

comments that get turned into documentation (javadoc, godoc, whatever c# has with them xml thingies, etc.) are good

pretty much all other comments are bad

sometimes you should use them -- but probably you should just write better, less clever code

suggesting that most comments are the result of code that is too clever is pretty wrong imo. i read lots of code that is neither obvious nor "too clever" and im quite thankful that it has comments

# ? Nov 30, 2016 00:11

MononcQc: May 29, 2007

I write comments longer than the code they document sometimes.

# ? Nov 30, 2016 00:39

ThePeavstenator: Dec 18, 2012; Establish the Buns

Comments should be kept a guarded secret until you reach a certain level of skill because a common early habit that never leaves bad devs is to write poo poo code and then go /*whoops this code is terrible but ill explain all of it here lol*/ instead of asking for help to write something correctly the first time. Also writing javadoc type blocks over every single piece of code that they write.

# ? Nov 30, 2016 00:56

DONT THREAD ON ME: Oct 1, 2002; by Nyc_Tattoo; Floss Finder

comments should be left as an exercise for the reader

# ? Nov 30, 2016 01:21

geeves: Sep 16, 2004

MononcQc posted:

I write comments longer than the code they document sometimes.

That's because you're using erlang...

# ? Nov 30, 2016 03:29

Stringent: Dec 22, 2004; image text goes here

somebody somewhere in here said something like "let the code say what and the comments say why" which i've found to be p good advice

# ? Nov 30, 2016 04:08

anthonypants: May 6, 2007; by Nyc_Tattoo; Dinosaur Gum

Stringent posted:

somebody somewhere in here said something like "let the code say what and the comments say why" which i've found to be p good advice

i know "why" comes up a lot when i'm looking at something i wrote in the past

# ? Nov 30, 2016 04:10

geeves: Sep 16, 2004

anthonypants posted:

i know "why" comes up a lot when i'm looking at something i wrote in the past

Yeah, I think that phrase was originally from Clean Code and has been misinterpreted since.

# ? Nov 30, 2016 04:11

Stringent: Dec 22, 2004; image text goes here

geeves posted:

Yeah, I think that phrase was originally from Clean Code and has been misinterpreted since.

ah right, that's it. that was a really good book, i should reread it.

# ? Nov 30, 2016 04:15

MononcQc: May 29, 2007

geeves posted:

That's because you're using erlang...

I do the same for commit messages sometimes v :shobon:

v

I've wondered what the implications would be of GPL'ing a commit messages in a project's history.

# ? Nov 30, 2016 04:19

Stringent: Dec 22, 2004; image text goes here

lol

# ? Nov 30, 2016 04:23

geeves: Sep 16, 2004

MononcQc posted:

I do the same for commit messages sometimes vv

I've wondered what the implications would be of GPL'ing a commit messages in a project's history.

Joking aside, I would love it if you sat next to me at work

I like good commit messages. Good ones build a great code review / pull request message to help understand what's going on if I'm a dev reviewing, but not familiar with the part of the app - which I spent too much of my time these days tracking people down and asking what they meant by something when I should just reject the PR and tell them to do better (they're not letting me add a git hook for a larger commit message because the CTO likes his mini-checkin messages).

# ? Nov 30, 2016 04:32

Brain Candy: May 18, 2006

the act of writing doc-style comments is useful in itself because thinking about an api is different than thinking about the innards. i find some of the sharp edges when i try to explain how to use whatever i've written

since i'm lazy and coding is easier than writing good comments, it pushes me to change the api so i don't have to explain

# ? Nov 30, 2016 04:32

EIDE Van Hagar: Dec 8, 2000; Beep Boop

MononcQc posted:

I do the same for commit messages sometimes vv

I've wondered what the implications would be of GPL'ing a commit messages in a project's history.

my favorite commit messages are the ones that end in ", again"

like "removing script generated files that should not be committed, again"

# ? Nov 30, 2016 04:35

the talent deficit: Dec 20, 2003; self-deprecation is a very british trait, and problems can arise when the british attempt to do so with a foreign culture

Brain Candy posted:

the act of writing doc-style comments is useful in itself because thinking about an api is different than thinking about the innards. i find some of the sharp edges when i try to explain how to use whatever i've written

i like unit tests for this same reason

# ? Nov 30, 2016 05:43

Bloody: Mar 3, 2013

C.H.O.M.E posted:

my favorite commit messages are the ones that end in ", again"

like "removing script generated files that should not be committed, again"

me, in our svn, sisypheanly, as random idiots commit insane garbage

# ? Nov 30, 2016 06:06

Wheany: Mar 17, 2006; Spinya^{ha^{ha^haha}ha}ha_{ha_{ha_haha}ha}ha!; Doctor Rope

i had some code where an objet was returned by a method. the method was annotated @Nullable in the super class, but our overriding implementation never returned null

our linter complained about using a possibly nullable object without checking for null, so i added an assert to shut it up. i also added a comment explaining that

someone changed the preceding code so that the object no longer came from a @Nullable method, but never removed the assert or the comment. then someone copy-pasted the same snippet to another file, so now the incorrect comment and assertion was in two places.

thankfully someone caught it some time later in code review, but i had to scratch my melon for a while to understand the events that lead to that

# ? Nov 30, 2016 08:03

Weekend Bridges: Apr 8, 2015; by Smythe

Stringent posted:

somebody somewhere in here said something like "let the code say what and the comments say why" which i've found to be p good advice

i like 'a comment is an apology'. doc comments are great, regular comments almost always mean you didn't factor well enough

# ? Nov 30, 2016 08:11

Stringent: Dec 22, 2004; image text goes here

Weekend Bridges posted:

i like 'a comment is an apology'. doc comments are great, regular comments almost always mean you didn't factor well enough

an example of the kind of comment i'm talking about is one i just made on a bit of code that has to send a request to an external service

code:

# fields marked as optional in docs, but request returns 400 if not present

without the comment someone (me) just looking at the code later on is going to wonder why those two fields are present with static placeholder values and possibly just remove them.
i've done that kind of thing enough at this point to spot some foot guns in advance.

# ? Nov 30, 2016 08:28

Chalks: Sep 30, 2009

Stringent posted:

an example of the kind of comment i'm talking about is one i just made on a bit of code that has to send a request to an external service
code:
# fields marked as optional in docs, but request returns 400 if not present
without the comment someone (me) just looking at the code later on is going to wonder why those two fields are present with static placeholder values and possibly just remove them.
i've done that kind of thing enough at this point to spot some foot guns in advance.

Yeah, the "a comment is an apology" concept might work well in a world where you're responsible for every line of code, but as soon as you start interacting with third party libraries that don't necessarily function in a sensible way, you're going to be commenting workarounds and unusual behaviour pretty often.

I write integration with accounting system software that's been around for decades and that stuff works in the most bizarre ways, often undocumented. Comment dat poo poo.

Shaggar posted:

Gotta optimize

To be fair it was interfacing with a language where integers are actually shorts, longs are actually integers and in order to use a long, you have to use a datatype called a longlong. I guess that makes it a bit less surprising that this sort of poo poo happens. What I'm saying is, never touch SAP Powerbuilder.

# ? Nov 30, 2016 09:41

Weekend Bridges: Apr 8, 2015; by Smythe

Chalks posted:

Yeah, the "a comment is an apology" concept might work well in a world where you're responsible for every line of code, but as soon as you start interacting with third party libraries that don't necessarily function in a sensible way, you're going to be commenting workarounds and unusual behaviour pretty often.

I write integration with accounting system software that's been around for decades and that stuff works in the most bizarre ways, often undocumented. Comment dat poo poo.

alternatively, wrap it in a more sensible interface that can ensure proper access to the broken one. it's not always possible and it depends on how expressive your language is, but the great, great majority of the time there's nothing stopping you except putting the effort in, and that way you end up with a significantly more robust solution. sometimes you don't have the time to fix things, but i think it's worth keeping in mind that needing to comment things virtually always represents settling like that

# ? Nov 30, 2016 10:45

Chalks: Sep 30, 2009

Weekend Bridges posted:

alternatively, wrap it in a more sensible interface that can ensure proper access to the broken one. it's not always possible and it depends on how expressive your language is, but the great, great majority of the time there's nothing stopping you except putting the effort in, and that way you end up with a significantly more robust solution. sometimes you don't have the time to fix things, but i think it's worth keeping in mind that needing to comment things virtually always represents settling like that

Yeah, but often it's not just the usage but the behaviour - as in, you're setting a combination of settings for a reason besides their obvious purpose. In cases like that "proper" access is difficult to define since enabling one feature requires the alteration of settings that affect other features - putting that behind an interface makes those interactions less clear. You go from needing a comment to explain why you're altering other settings, to the developer not knowing those other settings are being altered at all which can lead to further problems. As a minimum, your wrapper would need to document the reasons for the calls you're making in comments.

# ? Nov 30, 2016 11:09

Weekend Bridges: Apr 8, 2015; by Smythe

Chalks posted:

putting that behind an interface makes those interactions less clear. You go from needing a comment to explain why you're altering other settings, to the developer not knowing those other settings are being altered at all which can lead to further problems.

if those interactions are still visible to users of your wrapper, then you wrote a lovely wrapper

quote:

As a minimum, your wrapper would need to document the reasons for the calls you're making

right

quote:

in comments

huh?

# ? Nov 30, 2016 11:44

raminasi: Jan 25, 2005; a last drink with no ice

Weekend Bridges posted:

if those interactions are still visible to users of your wrapper, then you wrote a lovely wrapper

right

huh?

I believe the point is that somewhere you have to write weird code, no matter how many layers of abstraction you hide it behind, and that weird code should get comments, because it's weird code

# ? Nov 30, 2016 14:07

Stringent: Dec 22, 2004; image text goes here

Weekend Bridges posted:

alternatively, wrap it in a more sensible interface that can ensure proper access to the broken one. it's not always possible and it depends on how expressive your language is, but the great, great majority of the time there's nothing stopping you except putting the effort in, and that way you end up with a significantly more robust solution. sometimes you don't have the time to fix things, but i think it's worth keeping in mind that needing to comment things virtually always represents settling like that

This makes sense if you're dealing with backwards compatibility. If you're doing it to a moving target the only possible benefit is job security.

# ? Nov 30, 2016 14:15

Adbot: ADBOT LOVES YOU

# ? May 25, 2024 22:57

Chalks: Sep 30, 2009

Weekend Bridges posted:

if those interactions are still visible to users of your wrapper, then you wrote a lovely wrapper

I think we're talking cross purposes. Say you're writing software that interacts with an archaic accounting system. In order to enable feature A, you have to change 4 different settings, each of which have a primary purpose entirely unrelated to what you're trying to achieve. If you write a function of "EnableFeature()" that just does all of that, a developer using it will suddenly find different parts of the system behaving differently than they expected. They may go and change some of those settings back after making the function call, or go into your wrapper and remove the lines that are changing these settings because why the hell are these lines of code there anyway?

Little do they know that you spent a week wrestling with this archaic and barely documented system to discover that these settings have to be set a certain way for the feature to work without exploding at some point in the future. Fortunately, commenting your apparently random code avoids this confusion.

raminasi posted:

I believe the point is that somewhere you have to write weird code, no matter how many layers of abstraction you hide it behind, and that weird code should get comments, because it's weird code

Exactly - when you're starting from scratch you can always refactor your stuff so that it's clear (I mean who the hell writes a feature as a side effect of a bunch of other settings being set to invalid or unusual values?) but when you're dealing with 20 year old third party systems they tend to be written by piling random bullshit on top of stuff that nobody really thought through, and weird code is the world you live in.

# ? Nov 30, 2016 14:57

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > YOSPOS > terrible programmers: my god, it's full of chars

«‹›1446 »