Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

Author
Message
pictionaryjr
17
Years of Service
User Offline
Joined: 12th Mar 2009
Location:
Posted: 1st Nov 2012 09:43 Edited at: 1st Nov 2012 09:44
Alright I've gotten to a point in my program which I am going to start commenting. No lol the program is not finished. I just want to get a headstart on it so if I do have to go back and change any area of the part I've just finished, I'll understand it. I was wondering what commenting strategies you use to help you understand and break apart code. Obviously I don't want to comment every line of code or should I? I'm just wondering how you all do it.
Mine generally goes something like this:


I generally point out major parts with "rem" and point out minor details and explanations with "`". I also use "remstart" and "remend" at the beginning of my program to state creation date and author and before functions to explain the use of and how to use them.
MrValentine
AGK Backer
15
Years of Service
User Offline
Joined: 5th Dec 2010
Playing: FFVII
Posted: 1st Nov 2012 10:03 Edited at: 1st Nov 2012 10:09
I am 100% modular even on small projects just to keep the habit of doing so, and create functions in them pretty much entirely and then call them from the main source file...

And pretty much use "`" more often than I should but I often do this



But my main source file pretty much only contains the default [for now] Author and creation date information, and then simply a bunch of function calls to modulated source files, and the main loop, again containing just
EDIT Function calls...

Hope this was useful...

EDIT

Oh and I use the terms start here and end here as sometimes I may have multiple functions for particular elements of DBP, such as PHYSX [Dark Physics/Dark Dynamics] in a single source file, and want to split various functions apart.

Mr909
14
Years of Service
User Offline
Joined: 2nd Jun 2012
Location:
Posted: 1st Nov 2012 18:19
Personally, I use // for cleanliness. It's easy to just add or delete slashes to make a bigger point (Instead of dividing them like MrValentine does with `****************). For larger blocks (like where I remind myself what each value stands for in my CASE variables, or for your creation details) I would use REMSTART and REMEND. As I talked about it the Coding Style Weirdness thread, it really just depends on what you feel works for you and, if you're trying to adapt for other users, what works for the group.
MrValentine
AGK Backer
15
Years of Service
User Offline
Joined: 5th Dec 2010
Playing: FFVII
Posted: 1st Nov 2012 19:50
Mr909 - Please take a closer look again at my code... it is not a CHUNK comment...

The Weeping Corpse
14
Years of Service
User Offline
Joined: 19th Sep 2011
Location: United Kingdom
Posted: 1st Nov 2012 20:39 Edited at: 1st Nov 2012 20:42
Quote: "Personally, I use // for cleanliness"


Agreed.

I've been programming for over 20 years and I settled on a commenting style and a work regime early in my career. I comment every function like so,



1) If a section of code needs more than 10 lines to achieve its goal, I move it into a function.

2) I NEVER use goto or gosub EVER. Havnt since I owned an 8 bit zx spectrum.

2) place comments next to important, non-obvious variables, like so



3) wrap debug code like this



4) backup at the end of each session or you WILL regret it, but keep it simple, copy paste your code into an email and send it to yourself. free, easy and quick.

/RAMBLE

pictionaryjr
17
Years of Service
User Offline
Joined: 12th Mar 2009
Location:
Posted: 1st Nov 2012 21:55
@Weeping: I especially like how you document your functions. I also never use gosub or goto. I figured out it was bad programming habit and like now for my code to flow like I'm reading it. I also try to create as many functions for as many uses as possible, just to break the code up and make it cleaner.
I should start doing something along those lines. I'm just trying to figure out what the community does because if I do decide to release source codes for any of my projects. I want them to be easily understandable for the community.
Mr909
14
Years of Service
User Offline
Joined: 2nd Jun 2012
Location:
Posted: 1st Nov 2012 22:45
@MrValentine: My apologies for the misunderstanding, I didn't mean to call it that. I just said you used lines of asterisks to divide things where I used // (for any given type of "things")
Phaelax
DBPro Master
23
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 2nd Nov 2012 01:05
Quote: "2) I NEVER use goto or gosub EVER. Havnt since I owned an 8 bit zx spectrum."

I never use GOTO, but I will use GOSUB. It makes it a lot easier to see the flow of the program in the main loop.

"You're not going crazy. You're going sane in a crazy world!" ~Tick
MrValentine
AGK Backer
15
Years of Service
User Offline
Joined: 5th Dec 2010
Playing: FFVII
Posted: 2nd Nov 2012 02:24
Quote: "@MrValentine: My apologies for the misunderstanding, I didn't mean to call it that. I just said you used lines of asterisks to divide things where I used // (for any given type of "things") "


No need for an apology, I often make similar misinterpretations when I am dead tired...

GoSub is handy indeed! check the Code Snippets sections of the site for some crafty uses!

I often use "//" in PHP etc, and grew a bad habit of using "`" in DBP, I know I should move the "//" but a single stroke is faster when prototyping, however when I am working on a commercial app [1 so far] I tend to stick to regular conventions

TheComet
18
Years of Service
User Offline
Joined: 18th Oct 2007
Location: I`m under ur bridge eating ur goatz.
Posted: 2nd Nov 2012 11:52
@ The Weeping Corpse

Funny story, at a company I worked for they didn't like having comments in their code. Instead, they used variables and functions like this:





Don't do that please, use comments!

TheComet

- The codebase
Kezzla
17
Years of Service
User Offline
Joined: 21st Aug 2008
Location: Where beer does flow and men chunder
Posted: 2nd Nov 2012 12:20
Quote: " Instead, they used variables and functions like this:"


Yeah, I'm a little guilty of that one, Not as badly as your example though, I just like the variable or function name to be self explanatory.
for the record I also comment my code regardless. Kezzla 4 months from now needs to know what I'm doing.

I find that simple and obvious code blocks can get away with minimal commenting, eg setup screen resolution, framerate, bgcolor, fog etc. It is obvious what is happening in that code block and so basic explanation is sufficient.

Anything that has multiple levels of process, or sends information to another function and returns data before moving on is worthy of deeper explanation. I have no issue writing paragraphs of comment just to remind me in the future what is going on in this scattered section.

nothing worse than chasing logic through several nested functions on an old project. especially after you have made some headway on a cool new process, only to have it screw up due to something in the nested function chain.

what they say is true, a few months from now, someone else may as well have coded it.

Green Gandalf
VIP Member
21
Years of Service
User Offline
Joined: 3rd Jan 2005
Playing: Malevolence:Sword of Ahkranox, Skyrim, Civ6.
Posted: 2nd Nov 2012 13:44
Quote: "what they say is true, a few months from now, someone else may as well have coded it."


I'm convinced that someone else did write a lot of my old code.

Just spent ages trying to work out why an old demo no longer worked. The problem was easily fixed (it was a victim of changed DBPro functionality ) but it took a long time just to work out what I'd been doing and why - and that was with comments. Without comments I'd still be puzzling over parts of the code.
Jambo B
16
Years of Service
User Offline
Joined: 17th Sep 2009
Location: The Pit
Posted: 2nd Nov 2012 19:20 Edited at: 2nd Nov 2012 19:25
I do a lot of C++ as well, so I stick with //. My feeble brain would melt otherwise. Agree with commenting functions. I tend to include a brief comment to avoid too much typing:



Cheers,

James
Libervurto
20
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 4th Nov 2012 10:09
I think this is actually one of the more difficult things about programming.
Looking at your example you write comments in a "descriptive" style, as if your comments are instructions on what should be written below, this is a bad habit picked up from tutorials where these types of comments are used to re-enforce the meanings of commands.

There's no need to comment individual commands. If the reader doesn't know the commands they can read their manual.

You should not describe what you are doing but what it means for the program.

What are these boxes for? Why are you placing them there? Why are you rotating them? If these are not particularly significant actions then they don't need to be annotated.


This comment is fine because it isn't immediately obvious why you are storing these values. Note that you naturally explained the meaning of these variables rather than describing the process of assigning them. That's what your other comments should be like.

Now look at how we can apply this thinking to conditional loops

becomes

The invariant is a statement that is always true at a particular point in the loop, usually placed at the start or at the end of a conditional loop, these can be very useful for quickly understanding the workings of a loop.

The last one is just about neatness:

This looks a bit messy to me and the lack of spaces around the equals signs don't help clarity. I'd suggest doing something similar to what weepingcorpse suggested for something like this, but it does make me wonder whether you couldn't create separate arrays or use constants as labels instead of having to deal with all these cryptic numbers.

So to reiterate, my one piece of advice would be: don't DESCRIBE what you're doing, EXPLAIN what you're doing. If that makes sense.

Shh... you're pretty.
Ortu
DBPro Master
18
Years of Service
User Offline
Joined: 21st Nov 2007
Location: Austin, TX
Posted: 4th Nov 2012 22:20 Edited at: 4th Nov 2012 22:25
The array would really benefit from being set to a UDT
It makes things much more readable and self explanatory, removing the need to provide a map to the array (1=position x) in comments.



Login to post a reply

Server time is: 2026-07-11 14:51:45
Your offset time is: 2026-07-11 14:51:45