[BMAX] When is it right to indent and comment?

[Dra_chan]

Hello, I just started learning Blitzmax and P_O told me people here are the best programmers he knows, and that you could give me good advice. I have no previous experience as a programmer, but i'm very interested in learning. I have two questions. When do I need to indent? I want to write readable code! And, when is the best time to comment on code? I'm a really messy person, so some advice will come in handy.

Here is the code product of P_O's lessons. Thanks in advance!

Code: [Select]

SuperStrict

Graphics(640, 480, 0)

Global ship_image:timage = LoadImage("ship.png")

Type ship

     Field x:Int, y:Int

Method draw()

DrawImage(ship_image, x, y, 0)

End Method

Method move()
x = MouseX()
     y = MouseY()

EndMethod

Method Update()

move()
draw()

End Method

End Type




  Global my_ship:ship = New ship
 
  my_ship.x = 10
  my_ship.y = 20
 
  my_ship.draw()
 
  HideMouse()

  While not keydown(key_escape)
 
  Cls
 my_ship.update()

 Flip

 Wend


[Pixel_Outlaw]

I tried to explain but came up short.

     I basically said that you want to indent after you start a new loop, then return to the original position after you exit that loop. My words are failing me a bit. She is a really good student and I'm just trying to get her making something in Bmax. I planned out a little lesson that will incorporate most of the most used stuff. I just am having a great time teaching her my limited knowledge. I feel that my explanation is somewhat unhelpful. I told her to get some opinions here since you guys may be better with explaining. I know when to indent and have my own style but I cannot explain why I do. It is just a gut feeling of when to indent and comment. I comment on anything that may be vague or hard to understand later for myself and other people who might read my code. Plus I wanted to have my chat buddy have a good programming foundation and start which can be found here.

My code is as follows: (Extra comments for her since she is beginning, also looks like the codebox is making my TABs huge!)

Code: [Select]


SuperStrict

'call our graphics move and create the window
Graphics(640, 480, 0)

' create a new ship timage by loading our sprite
Global ship_image:timage = LoadImage("ship.png")

' make a type (blueprints) for the ships we want to creaate
Type ship
     Field x:Int, y:Int

'draws the ship image at the x and y
Method draw()
DrawImage(ship_image, x, y, 0)
End Method

'makes the ship move along with the cursor
Method move()
x=mousex()
y=mousey()
End Method

'calls both draw and move in a single command
Method update()
move()
draw()
End Method

End Type

' make a new ship for the player using the ship type
Global my_ship:ship = New ship
my_ship.x = 12
my_ship.y = 12
my_ship.draw()

hidemouse()
' main game loop here, will continue to run as long as keydown(key_escape) is NOT true
While not keydown(key_escape)
Cls ' clear the screen buffer of old data
my_ship.update() ' update the ship
Flip ' flip the screen buffer to show the ship image we have drawn to it
Wend


She mostly just followed what I was talking about verbally. Again just some thoughts on these two subjects and welcome a new programmer into the world.

[hellfire]

Welcome to the forum Dra_chan!

Indenting, spaces and newlines are used to structure your source, making it easier to read for you.
It's not much different from layouting general text and there's no best way to do it, it's just important that it works for you.
Usually indenting is used to mark hierarchical structures, for example code inside a loop, a loop inside another loop or a function inside a type. It also helps to identify commands that belong together (while..wend for example).
Generally you should make it easy for the reader to follow the code and to find relevant pieces by structuring interrelated code into blocks.

Basically the same applies for comments.
At the moment you write some lines of code you're perfectly aware of what you're doing, but when looking at the same code a month later you might not have the slightest clue anymore - a few comments can really help.
First of all you should try to choose self-explanatory names for functions, types and variables so that you can follow the code by just reading it.
It's never necessary to comment every line of code (if it ever is, you should break up your code into smaller pieces), but it's a good idea to write a short comment at the beginning of each logical block telling what you do and why you're doing it.

As soon as your source grows a bit longer you'll use these concepts as a matter of course.
Both aspects are very much a matter of personal taste and every programmer handles it slightly differently.
Another key-element of structuring source is to hold self-contained and reusable pieces in different files (and with an increasing number of files also in different sub-directorys).

[Shockwave]

I just use indentation to make the code I write more easy for me to read, as has been said up above, relational blocks of code should follow the same format so that you can easily see which bits are related.

For example;

Code: [Select]

if something then

     do something
     do something
     do something

else

     do something
     do something
     do something

end if

Another thing I like to do in my listings to make them easier to read is to use white space (blank lines) to seperate things as you can see in the code block above.

Yet another thing I like to do to add an extra visual cue is to highlight important chunks of code (like the main loop, functions etc) with a comment followed by a line of some character like this;

'-------------------------------------------------------------------------

There are no hard and fast rules on doccumentation and indenting your code unless you are working profesionally as part of a team, they may insist that doccumentation is done in a specific way.

[Hotshot]

Welcome to the forum Dra_chan!

BlitzMAX is interesting language with OOP 

[zawran]

Welcome to the programming world, hope you enjoy it

Most important in BMax is to use SuperStrict, as it will force you into having to declare variables, which takes away a lot of the guesswork when looking at the code. You will know right away what kind of variable you are dealing with.

I usually use a one line comment in front of functions and methods to explain to myself what they are ment to do. If needed due to multiple input parameters and complicated input I use more than one, but usually try to stick to just that one.

If something else require explaination I usually try and stick a one line comment on the end of the code line. I would say that its better to have a little extra comments than too few. Especially since you probably will end up looking at the code several months or more later and then you might wonder what is going on, where the comments might have saved you time trying to figure it out.

I have used BMax since it first arrived and I am extremly pleased with it and I think you will be pleased that you have choosen it as your language as well. I am not as active with programming as I used to be, but I do check the forum on a regular basis and do try and answer all posts regarding BMax if I can.

Once again welcome to the world of programming and I wish you all the best and I will be looking forward to see your programs

[Hezad]

Heya Welcome on board !

Nothing to add about indentation since all posts here are pretty explanatory

For future BMAX questions/posts, please take a look at the Blitz category of the "Other Programming Languages" section 

Welcome again 

[Dra_chan]

Thank you for all your answers, they are very helpful. I will make sure to read the BMAX topics often. I like how people here give understabdable answers for people who are just learning.   

[JL235]

This is how I indent:

• Always indent when starting a new class, function/method, if statement, for loop or while loop.
• Never use tabs (unless the editor is using soft tabs which means it's actually using spaces)
• Always indent by 4 spaces.
• indent twice when continuing a line of code onto a second line

But whatever style you use, two rules are crutial. First don't make up your own, use others instead. Second, stick to it. Being consistent when writing your source code is one way to help make it predictable. Predictable code is easier to read, refactor and maintain.

For commenting, I have two types of comment. Documentation for classes/methods/functions and comments for fields and lines of code. Documentation should always be compulsory and written in full. If the language I'm using doesn't have a set standard for documentation then the style I use is a JavaDoc esc one I made up. It's approximately:

Code: [Select]

'************************************************
'        MyKlass class
'
' A description about the class, what it does, what it should do,
' known bugs, known other problems, what you might expect it to
' do but doesn't and any other general info.
'
' @author:    JL235
' @version:    version number or date
'************************************************

'************************************************
'        methodName
'
' This is the description of the method. Any extra info or excess
' info about parameters goes here.
'
' @param:    firstParam - This is the description for what the
'            parameter takes and what it expects.
' @param:    secondParam - a brief second parameter.
' @return:    Only used if it has a return type.
' @see:    OtherClass.someMethod()
'************************************************(note that all the gaps use a set number of tabs (which is 4 spaces)).

Every class and every function/method has a full header like that. It's also written as I write code, not after. That can even help because if I am unsure what the method should do then writing out documentation is one way to help work out what I want from it. I also keep one class per file.

When reading your code people should be able to predict what it does. Comments are for sections of your code where it is hard for them to predict or easy for them to be wrong. It should also be used for any other oddities in the code like using magic numbers or assuming some far off global variable elsewhere has been mysteriously set at this point.

[Shockwave]

Welcome to the forum JL235