Xojo Blog: where are the comments in the code?

Just had a look at the latest Xojo blog

https://blog.xojo.com/2018/07/31/tutorial-active-words/

Nice tutorial, BUT: I would consider this code really poor simply because it is not commented at all.

That is really bad programming practice.

I do not saw a link for the project, did I miss it ?

You can find a link in the Spanish article:
https://github.com/aprendexojo/LinkDetectorTextArea

Thanks.

This is NOT production code and you have ample documentation to explain the code. Additional comments are not needed and would only clutter the code. No cause for complaint.

The whole article is one big long well-written comment.

I disagree. In my experoence beginners and even advanced users tend to get lost in unstructured and undocumented code. It would help greatly if the code would include comments specifiying which part does what. Not doing so is simply poor programming practice.

And no, the text does not provide that either.

And to excuse it by saying “it’s not production code so no need to care about comments” is not exactly teaching good programming standards.

I for one would wish that tutorial code is more akin to production code and actually teaches how code should look like, but you are of course free to disagree.

I agree with Markus. Comments are useful, even more so in tutorial code, to help show what’s going on. It provides extra clarity which the code in MouseMove desperately needs as there is a paragraph of text to explain 34 lines of code with 3 If-then statements and 2 For-Next loops.

Particularly in the case of something that is presented as a “tutorial”, the comments should out-weigh the code. There should be full explanations of not only WHAT is being done, but in a lot of cases WHY it is being done a particular way…

I agree with the ‘the code isnt commented’ … the article doesnt really cover it.

Im not even a fan of elseif because of the way it obscures (to me) the structure

For instance:

If CharPosAtxy(x,y) >= length Then if boundedWord <> nil then setStyleForWord( boundedWord, false ) mboundedWord = nil elseif me.text.mid(startPosition,1) <> chr(32) and me.Text.mid(startPosition,1) <> EndOfLine then for n as integer = startPosition DownTo 1 if me.Text.mid(n-1,1) = chr(32) or me.Text.mid(n-1,1) = EndOfLine then boundLeft = n exit end next for n as integer = startPosition to length if me.Text.mid(n+1,1) = chr(32) or me.Text.mid(n+1,1) = EndOfLine or n = length then boundRight = n+1 exit end next end

Is ‘explained’ as
‘This code is in charge of detecting the limits of the word under the cursor and finding if it is one of the active words registered for the class:’

How about:

[code]If CharPosAtxy(x,y) >= length Then
//if the cursor is at the end of the text, then we don’t have a word
if boundedWord <> nil then setStyleForWord( boundedWord, false )
mboundedWord = nil

//so if we aren’t on a space, and we aren’t at the end of a line,
elseif me.text.mid(startPosition,1) <> chr(32) and me.Text.mid(startPosition,1) <> EndOfLine then

//start here, and work backwards to find out where this word starts into boundleft
for n as integer = startPosition DownTo 1
if me.Text.mid(n-1,1) = chr(32) or me.Text.mid(n-1,1) = EndOfLine then
boundLeft = n
exit
end
next

//now do the same working forwards to get the end of the word into boundright
for n as integer = startPosition to length
if me.Text.mid(n+1,1) = chr(32) or me.Text.mid(n+1,1) = EndOfLine or n = length then
boundRight = n+1
exit
end
next

//now we know that the word starts at boundleft, and ends at boundright
end

dim isolatedWord as string = me.Text.mid(boundLeft, boundRight - boundLeft) //get the word

//see if it is in our list of words
dim check as pair = wordInDictionary( isolatedWord, boundleft, boundRight )

[/code]

and even then, Im not sure that

dim check as pair = wordInDictionary( isolatedWord, boundleft, boundRight )

adds much to

 linkedWords.HasKey(isolatedWord)

Mainly because I dont follow what the regex is doing… :slight_smile:

So the article is a clever piece of code, but tricky to follow, and likely to be ‘used as is’

thank you for your comments and advices for improving it! Sorry for not including the comments with the code. Next time I will include them! BTW: the link to the project is included right before the “Text Area Subclass” header. If you want to download it, click here.

As always, it’s great seeing how this devs community cares about improving every aspect of the craft!

Javier

Agree / to me too.

Example of code in FolderItem

[code]Dim f, g As FolderItem

f = GetOpenFolderItem(FileTypes1.Text)
If f <> Nil Then // if the user didn’t cancel…
If f.Exists Then // if it is a valid file…
g = Volume(0).Child(f.Name)
If g <> Nil Then
f.MoveFileTo(g)
MsgBox(“success!”)
End If
End If
Else
MsgBox(“File not found!”)
End If[/code]

Sometimes I am a bit lazy, but most of time I restructure this kind of code. Like:

If f = Nil Then Return / Or make a user report, depends

One clear line (3 with comments and separation line) instead of a block of indented code.

Same for If f.Exists.

As usual with code, it is not for today or tomorrow, it is commented and presented in a clean / clear way for, say, in six months / 1, 2, 3 ? year(s).

Also: the whole seems to me a bit complex. What about links instead of clickable single word(s) ?