documentation: what is the correct term, function or command

[mskuma]

Killswitch & I have been proof-reading and editing the English docs. Maybe some of you have noticed an inconsistency in the docs when there is reference to a PB library function or command, i.e. sometimes an item is referred to as a 'function', other times as a 'command'. I think it's worth making it consistent throughout using one or other. I am not sure which is the correct terminology, so I thought I'd ask for your vote. Thanks for your help.

[Dare]

Perhaps something that returns a value (other than an error code) can be a function, and something that doesn't (other than reporting success/failure) is a command.

Eg:

Abs() = Function.
ExamineDirectory() = Command.

Just a thought.

[mskuma]

Thanks Dare, that makes some sense.

Any other takers for this, or other approach(es)?

[PB]

Dare is right -- they're two entirely different things, and used in other Basics.
I see no reason to change them at all, unless one is used incorrectly somewhere.

[Flype]

imho,

Commands : for purebasic built-in command's set
Procedures : for user defined commands
Functions : for api, third-party dll, userlibs

but i'm probably strongly wrong :roll:

[mskuma]

I see no reason to change them at all, unless one is used incorrectly somewhere.

Yeah (assuming that logic which seems reasonable), currently it seems to be a bit mixed up in places, e.g. in the 2DDrawing & Console sections, which is why I wanted to update it. Thanks for your input.

[mskuma]

Perhaps something that returns a value (other than an error code) can be a function, and something that doesn't (other than reporting success/failure) is a command

I'm inclined to think that something that returns anything is a function (even success or failure like ExamineDirectory()), and something that returns nothing (e.g. ClearConsole()) is a command.

[Kale]

Something that returns a value (other than an error code) can be a function, and something that doesn't (other than reporting success/failure) is a command.

I would go with that. Functions tend to return something while commands might not.

Saying that though in my book, i called all built-in library commands, commands, to not confuse beginners.

Subroutine, function, procedure all seem to be interchangable and may or may not mean the same thing. I think it depends on your preference. You should just choose a definition, describe it early on and then stick to it throughout the text.

[Straker]

In general programming:

Command: Language-defined. Usually always mean the languages built-in functions/procedures. Known as the command set.

Function: User-defined. Returns a value.

Procedure: User-defined. May or may not return a value - mostly not; think GoSub/SubProcedure.

In PureBasic:

Command: Language-defined. PB Internal functions/procedures

Function: Generally refers to PB's internal commands.

Procedure: User-defined. May or may not return a value (although they always return a value even without ProcedureReturn).

[blueznl]

function: pb primitive that returns a value

(pretty much most commands (oops, there i go again ) such as openfile(), str(), even things like openwindow() etc.)

command: pb primitive that does not return a value

(if, then, else, elseif, while wend etc. etc.)

procedure: something written by the user, regardless if it returns a value or not

(as there is not much difference between procedures and functions, in fact there is no function keyword, so the word procedure would do)

as a generic term, one could refer to 'keyword'

[Killswitch]

Well, I prefer command due to my DB days where 'function' was the same as 'procedure' in PB.

[freak]

function: pb primitive that returns a value

(pretty much most commands (oops, there i go again ) such as openfile(), str(), even things like openwindow() etc.)

command: pb primitive that does not return a value

(if, then, else, elseif, while wend etc. etc.)

procedure: something written by the user, regardless if it returns a value or not

(as there is not much difference between procedures and functions, in fact there is no function keyword, so the word procedure would do)

as a generic term, one could refer to 'keyword'

Well, what you create with "Procedure" is a procedure (no matter if it returns something or not). I think we can agree on that.

If, (where'd you get a "then" from !? ), Else, ElseIf etc. are not Commands. They are Keywords.
They are part of the language syntax, which the compiler translates into code.

So to function/command: I see no difference in their meaning. (which is probably why they are mixed in the help)
I would not make a distinction between such functions/commands that return something and such that do not.
PB does not enforce this distinction. (you can use a command wich returns a value and not assign it to anything.)
So i do not see why there should be a difference in naming.

Another point is this: If they are named differently, and we change a command which formerly
returned nothing and make it return some error code for example, we'd have to all help text refering to it
from command to function (or the other way), which we will either forget completly (very likely ), or
where we are likely to overlook some mention of it and forget to change that.
So there are more inconsistencies again then.

Like Killswitch, i prefer "Command", as "Function" is used in other languages for what we call Procedures,
so it may be confusing.

[mskuma]

I agree that it should be one or the other, not both for the reasons freak indicated.

Like Killswitch, i prefer "Command", as "Function" is used in other languages for what we call Procedures, so it may be confusing.

I think using "command" is confusing for those who think commands are things you type on a CLI or DOS prompt. For other advice, I checked wikipedia, and the following was found:

Function and procedure often denote a subprogram that takes parameters and may or may not have a return value. Many make the distinction between "functions", that possess return values and appear in expressions, versus "procedures", that possess no return values and appear in statements [though this is not a distinction found in the C programming language].

http://en.wikipedia.org/wiki/Subroutine

---

In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell.

http://en.wikipedia.org/wiki/Command_%28computing%29

The above suggests to me that "function" is probably the correct term, from a general point of view. Also I'm leaning towards "function" because who ever first wrote the PB help file must have considered this issue also, since the docmaker tags use "function" to flag functions (commands) in the help doc, e.g. "@Function BackColor(Color)". That's not to say it's right or cast in stone, however - just another observation.

[Dare]

Hi mskuma,

How wide is your brief? That is, to what extent can you (or perhaps that should be "to what extent do you want to") modify the docs?

If we're not locked into using either one or both of "Function" or "Command" then perhaps you could go the whole hog and use extended terminology that is more accurate and perhaps also more meaningful to people migrating across from other languages?

And perhaps you could write a small "Conventions used in this document" (Notation and Terminology) introductory to minimise possible onfusion on things like Procedure/Function/Sub.

Again, just some thoughts.

Thanks to you both for addressing this!

[mskuma]

Thanks Dare for your comments.

what extent can you (or perhaps that should be "to what extent do you want to")

I was hoping we could get away with just a 'replace all' on one or the other to make it consistent (i.e. use only function or command, not both). Frankly, we're focussing on brushing up the overall doc in our limited time, and trying to avoid adding any new material (i.e. brief editing for clarity & spelling mistakes).

go the whole hog and use extended terminology that is more accurate and perhaps also more meaningful to people migrating across from other languages?

Given what was said in the wikipedia doc about functions, I thought that would not be necessary since it says that functions (& procedures) covers library items that return something and don't return anything, thus also covering the role of commands discussed here (though there is the argument of other's historical view on commands, which seems to be not covered in wikipedia, but it may be incomplete on that front).