Brontoforumus Archive

Please login or register.

Login with username, password and session length
Advanced search  

News:


This board has been fossilized.
You are reading an archive of Brontoforumus, a.k.a. The Worst Forums Ever, from 2008 to early 2014.  Registration and posting (for most members) has been disabled here to discourage spambots from taking over.  Old members can still log in to view boards, PMs, etc.

The new message board is at http://brontoforum.us.

Pages: [1] 2 3 4 5 6 ... 9

Author Topic: Programmers' Wanking Corner  (Read 20780 times)

0 Members and 1 Guest are viewing this topic.

Brentai

  • https://www.youtube.com/watch?v=DnXYVlPgX_o
  • Admin
  • Tested
  • Karma: -65281
  • Posts: 17524
    • View Profile
Programmers' Wanking Corner
« on: June 12, 2008, 10:24:54 PM »

Hello.  Today I would like to talk to you about comments.

What I would like to know is, is there any such as overcommenting?  Because if so, I'm guilty of it, and nobody has told me.  This is largely because I can never get an honest critique of my coding style, because A) it's not the sort of thing people generally stop to critique and B) everyone I know who knows an int from a hole in the ground is a total ass.  Not that I'm not counting the people here in that demographic, but when you're in the desert you can't complain about the sand in the water.

Anyway!  I've long suspected that I've been quietly discriminated against for putting too much English in my logical gobbledygook, so I'd like y'alls input on whether this is too much, not enough, or juuuuust right.

A (completely at random pulled out of my current project) example:

Code: [Select]
void SizeToClient(HWND hWnd, int width, int height)
{
// Set the size of a window based on the desired client area size
// hWnd: Handle of window to resize
// width, height: Desired client area width and height

RECT rcWindow; // Current dimensions of entire window
RECT rcClient; // Current dimensions of client area
int borderWidth; // Total width of non-client area
int borderHeight; // Total height of non-client area

// Get dimensions of whole window and client area
GetWindowRect(hWnd, &rcWindow);
GetClientRect(hWnd, &rcClient);

// Get the difference in size between the whole window and the client area
borderWidth  = (rcWindow.right - rcWindow.left) - rcClient.right;
borderHeight = (rcWindow.bottom - rcWindow.top) - rcClient.bottom;

// Resize window to make client area size match width/height
MoveWindow(
hWnd, // Window handle
rcWindow.left, // Window x position (keep)
rcWindow.top, // Window y position (keep)
width + borderWidth, // New window width
height + borderHeight, // New window height
true // Repaint window immediately
);
}

Pretty much everything I write follows the same format: one-line function summary, explanation of arguments, explanation of variables, a line before each logical chunk of code, and an explanation of arguments on any big function call.  Is this really so bad, or am I right to suspect that most programmers are simply very proud of their ability to read and write confusing language* and don't like having things explained to them?


* I've built something of a mini-career out of my proven ability to parse out broken code left by insane developers who will apparently explode if they write a single letter of any sort of documentation.
Logged

jsnlxndrlv

  • Custom Title
  • Tested
  • Karma: 24
  • Posts: 2913
    • View Profile
    • Website title
Re: Programmers' Wanking Corner
« Reply #1 on: June 12, 2008, 10:37:41 PM »

It's the latter.  Until you reach the stage where you're making concept ASCII art in your comments, you aren't using comments too much.  I don't use comments enough; when I get back to a project I've started and been distracted away from, I can never figure out what else I still needed to do or how to adapt new ideas to the structure that's already there because I have no idea what the hell I was trying to do.
Logged
Signature:
Signatures are displayed at the bottom of each post or personal message. BBCode and smileys may be used in your signature.

Kazz

  • Projekt Direktor
  • Admin
  • Tested
  • Karma: -65475
  • Posts: 6423
    • View Profile
Re: Programmers' Wanking Corner
« Reply #2 on: June 12, 2008, 10:39:29 PM »

I imagine any given programmer would rather look at code loaded with comments than talk to the person who put it together.  Keep it up.
Logged

Thad

  • Master of Karate and Friendship for Everyone
  • Admin
  • Tested
  • Karma: -65394
  • Posts: 12111
    • View Profile
    • corporate-sellout.com
Re: Programmers' Wanking Corner
« Reply #3 on: June 12, 2008, 10:57:28 PM »

What I would like to know is, is there any such as overcommenting?

No.  I'm with those guys.
Logged

Catloaf

  • Tested
  • Karma: 14
  • Posts: 1740
    • View Profile
Re: Programmers' Wanking Corner
« Reply #4 on: June 12, 2008, 11:12:21 PM »

Well there's such a thing as putting in comments like an sadistic ass wipe imbecile.

Such as if someone put all the comments at the bottom of the program and had a line number next to each one.  But the development environment doesn't have line numbers displayed and the idiot bothered to comment every damn line number in.
Logged

Brentai

  • https://www.youtube.com/watch?v=DnXYVlPgX_o
  • Admin
  • Tested
  • Karma: -65281
  • Posts: 17524
    • View Profile
Re: Programmers' Wanking Corner
« Reply #5 on: June 12, 2008, 11:19:47 PM »

So the next question is, would that be overcommenting or just stupid commenting?

...now that I could very well be guilty of.
Logged

Zaratustra

  • what
  • Board Moderator
  • Tested
  • Karma: 48
  • Posts: 3691
    • View Profile
    • Zaratustra Productions
Re: Programmers' Wanking Corner
« Reply #6 on: June 13, 2008, 03:55:49 AM »

I have this feeling that it'd be very hard to change the value of the arguments for that function and still maintain that perfect indentation for the comments.

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Re: Programmers' Wanking Corner
« Reply #7 on: June 13, 2008, 04:56:48 AM »

I've always assumed that you should write comments in such a way that it will greatly ease your replacement should you call in rich/get hit by a bus.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?

Thad

  • Master of Karate and Friendship for Everyone
  • Admin
  • Tested
  • Karma: -65394
  • Posts: 12111
    • View Profile
    • corporate-sellout.com
Re: Programmers' Wanking Corner
« Reply #8 on: June 13, 2008, 10:15:14 AM »

Well yes, that's sort of the idea.  Comments aren't for you, they're for other people.

Though they can be a pretty big help to you, too, if you haven't looked at your code in awhile.
Logged

JDigital

  • Tested
  • Karma: 32
  • Posts: 2786
    • View Profile
Re: Programmers' Wanking Corner
« Reply #9 on: June 13, 2008, 11:21:08 AM »

Comments are essential to ease understanding your own code later on. When you come back to this function in six months' time it should remind you what exactly you were thinking when you wrote it.

I'd say your level of commenting is adequate. You'll often see real-world source code in that omits commenting, but that doesn't mean it's good practice.
Logged

Kazz

  • Projekt Direktor
  • Admin
  • Tested
  • Karma: -65475
  • Posts: 6423
    • View Profile
Re: Programmers' Wanking Corner
« Reply #10 on: June 13, 2008, 11:21:30 AM »

As someone who will be doing more than dabbling with C++ in a few short months, I'll tell you that I'm going to comment like a fiend, because I will forget why I wrote something mere minutes after I've written it.
Logged

Brentai

  • https://www.youtube.com/watch?v=DnXYVlPgX_o
  • Admin
  • Tested
  • Karma: -65281
  • Posts: 17524
    • View Profile
Re: Programmers' Wanking Corner
« Reply #11 on: June 13, 2008, 02:14:14 PM »

I'd say your level of commenting is adequate. You'll often see real-world source code in that omits commenting, but that doesn't mean it's good practice.

That's the thing: I can count the number of real-world comments that I've ever seen on my hands.  It's either because professional programmers are utter dillweeds, they're constantly banging this shit out as fast as humanly possible and don't have time to translate to English, or they're purposely making it impossible to read to prevent reverse engineering.
Logged

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Re: Programmers' Wanking Corner
« Reply #12 on: June 13, 2008, 02:21:10 PM »

That's the thing: I can count the number of real-world comments that I've ever seen on my hands.  It's either because professional programmers are utter dillweeds, they're constantly banging this shit out as fast as humanly possible and don't have time to translate to English, or they're purposely making it impossible to read to ensure job security or a post-job opportunity as a contractor.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?

Bongo Bill

  • Dinosaurcerer
  • Tested
  • Karma: -65431
  • Posts: 5244
    • View Profile
Re: Programmers' Wanking Corner
« Reply #13 on: June 13, 2008, 02:51:41 PM »

There's no such thing as overcommenting, but there's such a thing as a useless comment. When in doubt, explain what you're up to. I like to write all the high-level comments before I write a single line of useful code, just to ensure my thoughts are structured. If it's in a part where logic matters, I tend to put a short comment anywhere the code doesn't look like English; if it's math, I usually write the formula in a comment above the calculation.
Logged
...but is it art?

Thad

  • Master of Karate and Friendship for Everyone
  • Admin
  • Tested
  • Karma: -65394
  • Posts: 12111
    • View Profile
    • corporate-sellout.com
Re: Programmers' Wanking Corner
« Reply #14 on: June 13, 2008, 04:19:03 PM »

they're constantly banging this shit out as fast as humanly possible and don't have time to translate to English

Best guess.  Deadlines are the enemy of quality programming.

Though Jr's theory is good too.
Logged

sei

  • Tested
  • Karma: 25
  • Posts: 2085
    • View Profile
Re: Programmers' Wanking Corner
« Reply #15 on: June 20, 2008, 01:58:50 AM »

Console.  I remember eConsole, way back in the day, being too laggy to be practical.  This thing runs fine on my machine, which is a bit old, and I've been enjoying the mother fuck out of the customizability and tabbed interface.  It might be a little guilty, but it's definitely a pleasure.

I've been developing with Ruby on Rails and grown rather sick of juggling 2-3 console windows in the alt-tab dialog at any given time.  This is proving to be pretty tits.  It's even got me using Cygwin again, though I may've fucked the configuration up a bit, since it just says "Cygwin" there and isn't showing that the console is tied up running tail.

(Linux isn't always an option, so don't both reminding me how awesome the ctrl+f# console switching stuff is.  Cygwin probably lets me use screen, but I for some reason still haven't looked into it.  I know I should.)

Anyway, action shot:


Note to self: @echo off, stupid.

EDIT: It might have been better to stuff this in a [programming] tools thread, or some kind of "old software that's new to you" thread, but I couldn't be bothered to make either.  I also have been liking Notepad++ a lot, but I've been using it a while, so I'm not quite riding a fresh enough thrill to make a new thread about it, proclaiming my love for it to the world.  (Also, I've been messing with Netbeans, so things could get scandalous.)
Logged

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Re: Programmers' Wanking Corner
« Reply #16 on: June 20, 2008, 04:13:05 AM »

I love this site.  And you should too.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Re: Programmers' Wanking Corner
« Reply #17 on: June 25, 2008, 05:58:38 AM »

Interview with the father of C++.  Linked to the printable version, because christ that site is ad-loaded.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Reference Books
« Reply #18 on: June 25, 2008, 06:20:43 AM »

For those of you interested in game development programming, I have rather enjoyed the texts supplied over here.  Some are a little dated, such as Swords and Circuitry, but most of these hit the topics pretty damn well, and use freely available tools when possible.

A few highlights

For those of you who can code, but are rusty on your math skills, can't go wrong with this one.

I don't have this one on my shelf, but I've heard two people back in college swear by this book if you plan on making money off your game.

And for those of you just starting?  Seriously try this book aimed directly at beginners.  It gets into some Direct X stuff, but it's pretty down to earth.  Assuming you're good with logic and computers that is.  You will have to deal with some MS stuff like the Direct X SDK.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?

MadMAxJr

  • Tested
  • Karma: 5
  • Posts: 2339
    • View Profile
    • RPG Q&A
Re: Programmers' Wanking Corner
« Reply #19 on: June 26, 2008, 08:32:26 AM »

Guess I am the only one interested in this topic.
 :sadpanda:
Anyway, for you .NET workers, here is a damn fine tool for coverting C# to VB.NET and vice-versa.  Useful for ASP.NET work or general function conversions.

Bonus: Bizzaro World Visual Studio is free.
Logged
"The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt." - Bertrand Russell

Got questions about RPGs?
Pages: [1] 2 3 4 5 6 ... 9