Printable Version of Topic

Click here to view this topic in its original format

UtterAccess Forums _ Access Modules _ Comments To Code Percentage

Posted by: JonSmith Dec 30 2016, 06:01 AM

Hi guys,

Someone at work has made a pretty horrid tool in VBA and want IT to support it. I have many issues with it, one being really poor code commenting.
On analysis out of the 5,800 lines only 2% were code comments.

I analysed alot of my work and I average around 25-30% code comments. I was curious if I do more or less than the average coder. Obviously 2% is waaay too low but I want to gauge what others consider reasonable.

I was able to do quick checks doing Mz Tools statistics so I guess this is only a question that people with addin's such as that can answer?


JS

Posted by: Marsupilami72 Dec 30 2016, 06:14 AM

I just did a quick count on the routine i am currently working on - about 10% of the lines are comments.

Posted by: Jeff B. Dec 30 2016, 07:10 AM

One reason for including comments in code is to help the poor sod who comes along later and has to figure out both "what" and "how" ... and sometimes that's me!

Posted by: GroverParkGeorge Dec 30 2016, 07:58 AM

I just checked one project on which I am at least the third or fourth developer to work. It has about 26% comments, and about 23% blank lines. That means close to half of the actual lines in the VBA are comments.

Unfortunately, a lot of those comments are useless. That said, every change I make has a comment indicating when and why I made that change.

Other projects I work on are probably quite similar.

Posted by: nvogel Dec 30 2016, 08:50 AM

I don't think there's any "right" percentage. Too many comments can even be a bad sign. If code is well laid out and meaningful variable names are used then fewer comments may be necessary.

"Change history" commentary is an example of where less can mean more. Assuming your code is in a suitable source control system and incremental changes are properly annotated when they are checked-in then adding such comments in the code itself is unnecessary and potentially misleading.

Posted by: jleach Dec 30 2016, 08:52 AM

>> Obviously 2% is waaay too low <<

What makes you say that?

Generally speaking, comments are bad. It indicates that the code itself is unreadable and that it needs to be explained. If the code is unreadable, it's not good code. Comments create another layer of garbage that need to be maintained along with the code itself (which pretty much never happens... if I had a dime for every comment that explained something from 10 revisions ago and only serves to further confuse matters when someone would try to read it now...) As a matter of course I pretty much ignore any comments in projects I see.

If a person feels they need comments to explain their code, what they really should be doing is working on better code architecture: breaking up complex routines into smaller, more focal routines; adjusting naming conventions so they're very easy to read at runthrough. Code comments should be restricted for the very rare cases of "we had to do this way because [usually approach didn't work because ____]" or for (very)light overview of a complex algorithm. Module headers is another acceptable place for light commenting.

Keep a higher level documentation explaining what and why (NOT in code comments), and keep the code clean and well-structured, and comments will no longer be required except in very rare cases. Good code tells its own story without needing a translator at every turn.

My 2cents (or, maybe just file this under Unpopular Opinions smile.gif )

Cheers,

Posted by: GroverParkGeorge Dec 30 2016, 09:07 AM

While I don't disagree with most of your comments, I do think there is some value in noting changes in the code. After all, what you're suggesting as an alternative is a separate document that "someone" has to keep track of and maintain "somewhere". In a full-blown IT project that's par for the course. However, in most of the small-medium sized Access projects I've worked on, clients tend not to want to pay for real documentation. I can think of only one project where that was the case, in fact.

In the absence of reliable source control for Access, the only way I know to maintain some semblance of sanity is to note changes in the code for other developers. For example, in a project that has been worked on by different people at different times, and currently has at least two active developers, I put this one:


'============================================================================
' RVK-- by Grover Park Consulting 10/14/2016 13:19 Changed the way new items are added to the list, at the top rather than the bottom
'============================================================================

Since I have no way to implement source control here, noting things I changed is a second-best alternative. Hopefully, the other guy won't overwrite my changes just because he has an older, different, version.

Here's an example of the kind of comment for which I do have some contempt, though:


'$ PURPOSE: Set the Date of the blanket fee
'$
'$ REVISIONS:
'$ 07-27-95 Original Version
'$ 00.03.15, reformatted, MjB.
'

Note that the original code dates back to July of 1995, by the way. Really? Cool. 21 years of code tweaks makes this one of my favorite databases to support. On the other hand, what got "reformatted" in 2015 by someone else whose initials are MjB? I have no idea, nor do I really care.

On balance, therefore I'd prefer not to have to do it, but until MS decides to restore some sort of usable source control, code comments are handy enough, IMO.


.

Posted by: jleach Dec 30 2016, 09:18 AM

Yea, lack of good SCC in Access makes revisions a pain, and I think commenting can be good for that within VBA. Rarely do I get an Access project that uses comments that way though... most times they're peppered (or saturated) throughout the code itself, which doesn't really help anything, IMO.

With that said, I do feel that separate documentation is valuable on any size project. It need not be elaborate, though it does take some discipline to properly maintain.

Cheers,

Posted by: GroverParkGeorge Dec 30 2016, 09:21 AM

Well, there's that pesky budget problem to manage, Jack. I just recalled a second project on which there was budget for documentation, but my little Access piece was one small corner of the whole thing. The client actually set up a Wiki for documentation and each developer, including me, was expected to manage our portion regularly (at least once a week, not "whenever"). But when the project budget is "as much under $5,000 as you can manage", it's hard to convince a client to include documentation. Far too many people consider it a "nice to have".

Posted by: Doug Steele Dec 30 2016, 09:31 AM

You might be interested in a column my friend Peter Vogel (former editor at Smart Access) wrote a few years ago, entitled https://visualstudiomagazine.com/articles/2013/06/01/roc-rocks.aspx. Follow the links at the top of the article too.

Posted by: GroverParkGeorge Dec 30 2016, 09:50 AM

Hmm. Thanks, Doug. Sometimes I tend to lose perspective a bit. "WHY" is useful. "WHAT" is often not so useful.

Posted by: jleach Dec 30 2016, 09:58 AM

Good article(s) Doug, they better articulate my points than I did.

A few things though:

>> I am not aware of any scientific studies that have been done to measure the effectiveness of various coding or comment styles. <<

Steve McConnel wrote about the subject of commenting rather in-depth in his Code Complete book (which every developer should read, IMO). I'm not sure offhand if this work was based on research, but most of his books do cite specific studies.

I disagree with this statement from the main article you linked to:

>> Refactoring is only reasonable if you're doing test-driven development (TDD). <<

For VBA, testing frameworks are about as readily available as SCC tools (ok, even less so). Nevertheless, refactoring should always be the "after working code is there" step, I think. (I wonder if the author is mis-using the word TDD here, as TDD is specifically the approach of writing tests before code, then coding until tests pass - I think he may have been speaking of unit testing more generically, which is surely a good thing, especially for refactoring, but refactoring is still reasonable in VBA, even without TDD (or even unit testing frameworks readily available))

Posted by: JonSmith Dec 30 2016, 02:00 PM

Nice to see its caused some discussion!!

nvogel, I wasn't looking for a "right" percentage. I was looking for an average. This is highly subjective so trying to find a "correct amount" would be dumb.



Jack, I have got to disagree with you fundamentally.
What you might consider readable code may not be readable to someone else. My code comment mentality is for each code block to explain the overall purpose of that code chunk and not for example that .copy would copy some information.

I would say if you are breaking your sections apart alot a description of the procedure is essential since when out of context of a larger procedure the behavior can make no sense. I don't always want to investigate 1000 lines of code to get the context needed to fix 5 lines worth.

Speaking first hand of having to fix alot of VBA tools created by others poor commenting is a huge time drain. I am an experienced coder, I understand all the VBA I see but I don't often know why the [censored] something is happening in some of the code I see until I slog through all the other lines around it.

An example is some awful code in Excel that was doing some rather messy SQL from a bunch of data sources, the SQL had loads of "", "", "", for its fields and none of the fields has fieldnames so I had to cross reference back the data to try and work out what was going where. It involved about 3 union queries. I followed it through until I found out it was simply summing column and column K. The empty fields were so it could be pasted into column A and the summed fields would be in the correct position. I re-wrote it to just use a simple formula and discarded over 100 lines.

If at any point the code had described that chunk as summing those columns I could have skipped so much time. It didnt. Now I see your point that if it had been written very simply at first the comments wouldn't be needed, I wouldn't explain what a sum formula does next to a sum formula, but I would explain a code chunk as it puts the totals of the relevant columns in.


I am curious Jack, since you feel comments aren't needed. Do you work with other peoples VBA often? Do others work with yours?


In the context of the issue I have at work, the department hired an external to build the VBA tool, its badly written in my opinion, they don't know how to code well (for example in the various class modules they have, and there is alot, they always use functions to return properties as they seem to be unaware of Get / Let), I also don't understand why most of the code will be doing the stuff it does as its about financial curves and I don't know how to do that. If I need to fix the thing I need to see what its supposed to be doing.
I have also come across things in the past that seem wrong to me, when I have no context of what they should be doing I then have to investigate alot, if I knew what it should be doing I can fix instantly.




Posted by: JonSmith Dec 30 2016, 02:06 PM

To put it another way, I agree that if code is of a high quality and the person reading it is skilled in VBA then comments are of limited use and can sometimes be a hinderance to maintain.

However how do we measure quality? I don't want to go through 5000 lines of code to evaluate the quality and inevitability have to rebuild it as I go because the quality is not as high as needed for the aforementioned to be true.
Instead, if the code is commented, if it is of a low quality it is still readable without too much effort, if its of a high quality less skilled VBA coders will then have much more chance of understanding it.

Posted by: jleach Dec 30 2016, 02:44 PM

I have worked with many other people's VBA code, yes. In general, when I inherit a brownfield project, the comments are bad and get ignore, often deleted as I work through the system. Bad comments are easy to write. Rare is the case I get a VBA project with worthwhile comments in it.

I'm not saying comments aren't needed or are across the board bad, but I do feel that most times they are. Few people seem to be able to strike the balance between good comments and bad comments (especially in the VBA world, but elsewhere also).


Here's an example procedure I use:

CODE
Public Function GetPendingUpdateCount() As Long
On Error Goto Error_Proc
'===============
    'variable declarations
'===============

    'function body

'===============
Exit_Proc:
    'cleanup
    Exit Function
Error_Proc:
    'handler here
    Resume Exit_Proc
    Resume
End Function



Aside from the "comment" lines that give visual separation to the anatomy of the procedure, there's no reason for comments (concerning separation of the anatomy of the proc: these help me quickly pinpoint the meat of the procedure - I typically don't care about the declarations (they're named so I don't have to), and I typically don't care about the cleanup or error handler: my eyes are trained to look at the signature or the body while skimming and ignore everything else).

I don't need a comment to explain what the code does. The signature does that.

I don't need a comment to explain how the code does it. I don't typically care how it does it, and if I do, I'll just read the code.

I don't need a comment to explain how it's being used. The module in which the procedure resides tells me that (and I should not be looking at functions without realizing what module I'm in).

Let's pretend I have some nasty bit of regex, which is entirely readonly. I could put a comment above that stating what it's supposed to be finding. Or, I could move whatever it's finding/doing to a smaller routine (which also creates an abstraction point for me to swap out that functionality later).

Some code is downright ugly, and not much to do about it. Heavily nested quotes are sometimes unavoidable. That may warrant a single, short comment (in very terse form) stating the intent or reason. Occasionally we'll have to do something in a slightly unorthodox manner that what other (experienced) developers might expect, so we'll toss a comment in there stating why (again, in very terse form).

A module header describing the core intent/basic approach as well as revisions is acceptable, I think, but not often required.



The other fairly strong argument for comments seems to be in helping other people that come along. As it happens, I have some thoughts on this as well smile.gif

First, I myself am not one to dumb down my code so a lesser-experienced developer can read it. Instead, I just assume have that developer work on something slightly above his/her level and learn a few things. Commenting code to help the less experienced is just making things more difficult for everyone else, provided the person who wrote the code is capable of writing good, readable code! (which is a very related subject but an entirely different rant).

If an experienced developer writes clean, readable code, any lesser experienced person should have no trouble following without comments leading the way (again, a module header describing the general intent/approach is fine - I'm talking comments within the code body). If a person is supposed to work with a project and can't understand what GetPendingUpdateCount() is supposed to do, there's an issue. If I use a DAO.Recordset to obtain that count within that procedure, I do not feel in the least bit obligated to describe what a DAO recordset is and why I'm using it to do the job (unless I had to use it in some very unorthodox way which wouldn't be expected elsewise). If the would-be-developer doesn't know that, they have no business working on the same project as whatever customer I might have written this code for (on the other hand, I wrote a data macro management utility for the Professional 2013 Access Programming book, and that code was heavily commented simply because it was intended to not only provide a useful tool, but to show other developers how to do it: explaining what XML nodes are and why we have to loop them using NextNode instead of a For loop or the data structures within the xml that make up the data macro definition, etc - that's an entirely different context but serves to show that it's not all black and white regarding comments).


>> What you might consider readable code may not be readable to someone else. <<

Readable code should almost be readable by a non-developer, at least to the point of giving an outline of what's going on, should they have any interest. What I consider to be clean, readable code should be readable by anyone with a small amount of programming experience. On the other hand, the ability to effectively and efficiently read code is also a skill to be learned, but again, I'm more inclined to give people something to learn than dumb down my work. I've had highly technically able developers do amazing work in a functional sense, but the code is a nightmare to work with because they didn't understand and apply the subtleties of good, semantic naming conventions (don't even get me started on this). I've had others do work for me that weren't all that technically superior, but their code is easy to work with because they have a good sense of readability.

In any case, I do disagree with your statement, again provided the person who wrote the code is capable of writing good, readable code. Such code should be readable by just about anyone.

Regarding quality: tough metric, but I'd say that a large part of that is having clean, readable code, because clean, readable code is maintainable code, and if your code is clean and readable enough where you don't need comments, that means you've followed many other best practices in code construction as well, which overall lends itself well to quickly and easily determining with a reasonable amount of confidence whether the codebase you've inherited is well constructed or not. So, it's not [i]just]/i] about comments, but many other unrelated factors as well: when they all come together, the code should speak for itself, and then you have a project that is a dream to work on and it easily turns into one of your favorites. Unfortunately, this is all too rare.

Cheers (good topic!)

Posted by: jleach Dec 30 2016, 02:53 PM

(as you might have guessed, I'm very OCD about code cleanliness and readability... in the .NET world (where most of my work is) this is most often abused by being trigger-happy with interfaces, but it's very much the same concept I think: the bottom line is that bespoke business software must be highly maintainable, and the cleanliness of the code is a huge factor in this. In fact, within my own business, it is my largest internal focus when getting people up to speed - get the naming conventions down, stop with the stupid fluff code, keep it short, sweet, neat and clean, because in three months when the client wants something modified, I want to be in and out quickly and effectively, while understanding what we're doing the whole time. Code without comments is a strong indicator that we've met this mark, and I've not heard anyone complain about it (but that may just mean that they don't complain to me))

Posted by: TheSmileyCoder Dec 30 2016, 04:49 PM

I took over a project which had plenty of comments. Sadly they were all of the style

CODE
'Enable error handling
On Error goto ErrHandler

...


'Rest error handler
On Error Goto 0

Hey, if it was the first time I ever used an error handler, I might do the same, just because the syntax was new to me. But in 200 procedures, that same piece of useless comment? While the things that actually required a comment had none:
CODE
Private Sub Frame281_AfterUpdate()
  ExecStoredProcedure "myStoredProcedureVersion8"
End Sub


I tend to agree with Jack. I would say most of code is self-documenting, but I might for readability or "scanability" the ability to quickly scan for the piece of code to modify, I might add some small comments to each code block like below:
CODE
'Generate excel instance
      Dim ws As Worksheet
      Set ws = gfh_CreateExcelApp(1).Workbooks(1).Worksheets(1)
      
   'Export data
      Dim myRange As Range
      Set myRange = ExcelTools.RecordsetToExcel(rs, ws.Range("B2"))
  
   'Add calculation column
      myRange.Range(myRange.Cells(1, myRange.Columns.Count), myRange.Cells(rs.RecordCount, myRange.Columns.Count)).FormulaR1C1 = "=RC[-1]-RC[-5]"
      myRange.Range(myRange.Cells(1, myRange.Columns.Count), myRange.Cells(rs.RecordCount, myRange.Columns.Count)).EntireColumn.Hidden = True
  
   'Add the chart
      Dim myChart As Excel.Chart
      Dim chartRange As Range
      Set chartRange = ws.Range("J2", "R26")
      Set myChart = ws.ChartObjects.Add(chartRange.Left, chartRange.Top, chartRange.Width, chartRange.Height).Chart
      myChart.ChartType = xl3DBarStacked
      
      With myChart.ChartArea.Format
         .ThreeD.RotationX = 0
         .ThreeD.RotationY = 90
      End With
      
      
      myChart.PlotVisibleOnly = False 'This sadly auto-creates a series
      'So now we delete it
      Do While myChart.SeriesCollection.Count > 0
         myChart.SeriesCollection(1).Delete
      Loop
      
      myChart.Axes(xlCategory).ReversePlotOrder = True
      
   'Format chart
      With myChart.SeriesCollection.NewSeries
         .Name = myRange.Cells(1, 3).Value
         .XValues = myRange.Range(myRange.Cells(1, 0), myRange.Cells(rs.RecordCount, 0))
         .Values = myRange.Range(myRange.Cells(1, 2), myRange.Cells(rs.RecordCount, 2))
        
         .Format.Fill.ForeColor.RGB = 5154185
        
      End With


You might notice the only comment that is more "sentence" like in nature, is about the series being auto-created, and hence deleted. That is an example of something I felt required a bit of explaning.

Posted by: jleach Dec 30 2016, 05:46 PM

I might even go so far as to break down each task in that procedure to a separate procedure. A proc should do one thing and one thing only (and if it means that the one thing it should do is instantiate an excel object and pass that to other procedures in a series of calls to perform a larger task, that's fine: but each task (export, add calc, add chart, etc), would be separate procedures).

>> 'This sadly auto-creates a series <<

An example of a Good Comment. Notes something out of the norm happening and why we have to handle it.

thumbup.gif

Posted by: JonSmith Dec 30 2016, 06:28 PM

Interesting thoughts Jack.

I fear you are thinking I want things such as 'Turn error handling on' commented. This is not the case, I am talking more about general functional comments about what the proc does or what a code block does, for public variables sometimes why they are public and where they get used etc etc.

In your example of GetPendingUpdateCount() am I supposed to know the purpose from the name alone? Because I dont.... Whats an update count? Where does it come from?
What is getting updated? I have a background in healthcare and now work in finance, the businesses dont translate, I dont know alot of the financial technical terms. I have a proc to calculate shock values. I have no clue what shocks are but because I described the purpose of the proc in my proc headers I dont need to.

The commenting I do is more like the SmileyCoders which I think is a good amount that doesnt get intrusive.

I fear your reliance on naming conventions is too narrow and procs themselves often need a simple explanation. Not to understand the code, to understand why the code is there (like to calculate shocks and do x with them).
Considering you break your procs up so much I'd think its more important.

I actually really dislike segmented code when its segmented for the sake of it.
As far as I am concerned if any code is used repeatedly in different places then separate it, if its sufficiently complex to make the main proc cluttered / harder to read then separate it. In SmileyCoders example I see no need to break that apart unless any chunk is reused.

Posted by: tina t Dec 30 2016, 07:10 PM

hi, guys, i really love it when a group of you get going on a topic like this. being a self-taught amateur, seeing professionals explain and discuss your various styles and practices helps me develop my own without feeling too lost at sea. thx! :) tina

Posted by: jleach Dec 30 2016, 10:29 PM

Hi Jon - no fear, I have an explanation for everything wary.gif

GetPendingUpdateCount()... given the context of this thread, no, I wouldn't expect anyone to know what it means - it means nothing on its own. It's just a name I pulled out of my head because I wrapped up a data sync feature this morning and the subject was near the surface. But... if you're working in a form that - say - is supposed to import data from an external source, and that external source data gets pulled into a staging table, and the form displays three top level metrics: number of pending updates, number of pending removals and number of pending additions... This is high level stuff, not code-level. That's what the form does, that's a primary task of this feature (that along with some detail info on what's getting imported, flagging rows as approved or not). Then, within the context of that form (e.g., you're working on that feature, you're programming in that code module), then GetPendingUpdateCount() would make much more sense. Given a context, the name shouldn't need any further explanation. Bear in mind that everything we do, everything we work on, is within some sort of context, and that context is generally very easy to get. While we're "in the thick of it" developing for that particular feature, we're hip deep in the context and "just know", just like that (insert snapping finger sound), exactly what GetPendingUpdateCount() means. In the most extreme case, let's pretend you just happen to land at that procedure by accident, without any context whatsoever. Even then, the basic context should be very easy to obtain, simply by looking at the name of the module. That'll at least give a rough idea of where you are, and if you just happen to be there by accident with no context and maybe it's a slight bit vague by looking at the module/form name... in that case, you're certainly not there to do any actual work anyway, so it really doesn't matter either way - you either have the map open or you don't, so to speak.

So no, the name GetPendingUpdateCount() doesn't mean anything within the context of this thread, but if you were to run into that "in the wild" (and if the rest of the code were well structured), the name should need no further information - especially if it happens to be sitting right between the GetPendingAdditionsCount() and GetPendingRemovalsCount() functions.

Very obvious in context, and I am purposely stressing the concept of context here because I think it's a fundamental concept that gets very little lip service but means very, very much in terms of how we "interact" with our codebase (more on this in a bit).



Let's switch to global variables. Personally, I hate them, don't ever use them, haven't in years. Why? They have no context. Because if I see a variable name that I don't recognize within the scope of my context, I have to break my train of thought and go find it. I hate that, because we're ridiculously more productive if our minds can work without breaking a smooth train of thought.

What to do instead? Put it in a property wrapper and call it via two-part naming. So simple, so effective. Instead of seeing glngCurrUserID (which, btw, my brain now needs to strip off the "glng" part and fill out "Curr" to "Current") - instead of seeing that, if I were to instead see Session.CurrentUserID, I have context. Right there, in two little programming words, I have the complete context of what this value is, where it's coming from, and - inherent to whatever "feature context" I'm working from, I will know how it will be used and applied. glngCurrUserID I have to think about - I have to stop my train of thought - even for half a second - and actually interpret it. Session.CurrentUserID is so obvious that I my train of thought doesn't even stumble (consider that difference in a whole procedure's worth of less-than-semantic-naming). Given how strongly I feel about such a little change, one might imagine what I think about having to go read a comment somewhere (at the source of the variable, I'm sure - a wooooorld away from where my mind is when I need, contextually speaking smile.gif ).

I understand that Session.CurrentUserID is a pretty generic and obvious example, but this concept applies across the board and I'm at lack of a more obscure example to better demonstrate at the moment... sorry.


I mentioned two-part naming there. At the start of this thread I thought it might come down to the topic of naming conventions, and I was really trying to not to bring it there, but here we are anyway. Two part naming: ModuleName.ProcedureName. What does that possibly have to do with comments and/or lack thereof?

When you're in the zone, and you're working with a "zone-enabling-project", you're in the zone and the project is enabling that zone because you have what you need well laid out and it's easy to find and understand and so on and so forth. If a project treats you that well, it's probably got some really nice naming conventions in play. Primarily through it's naming conventions and code architecture/structure, it's enabled you to fall into a context and stay within that context completely: that's the foundation of the true "zone" - when you are so completely immersed within your context that you don't even have to think about it - AND - that there's no requirement to look outside of your context, because that breaks the whole zone-context-primeproduction thing. As soon as you have to leave your "zone context" to go get something else from outside, your zone context falls apart a little and is a little less stable when you try to get it back. Do it more than a little bit and it falls apart completely.

If I have to read a comment, I'm most likely being tossed out of my zone context because I have to stop "semantic-think" to read and understand it (where in most cases, I could have instead just let the context and conventions do their job and would have never had to look outside). If I have to go find the source of a global variable and read the comment there, I'm way gone from my zone and productivity can suffer significantly (or rather, I'm then working at the same level as most other people instead of where I'd really prefer to be).

So let's go back to global variables again. Consider this:

BEFilepath

versus...

App.BEFilepath

Let's pretend two things: 1) you know that App is a module whose purpose is to hold application settings and properties, and 2) you're "in the zone" working through this whatever, and you come across the variable name in code.

In the first case, a lone BEFilepath (with no local variable named accordingly) is apt to make me have to stop and think. Where's that from? It's a global, right? I should double check that, [censored] - now I have to leave my zone for a minute, and 40% of my "zone" is missing (if I can find it my BEfilepath def quickly - within a second or two) when I get back.

If I see App.BEFilepath, I can keep moving on because I know without having to think about it, exactly what it is. Those four little characters (App.) may very well have just saved me half an hour or more of "zone time" because I didn't have to go looking for the definition to confirm my suspicion about what it is (let alone find out what it's supposed to be).

So, if I have a comment, and I have to read it, it's even worse than the original BEFilepath. Again for lack of a better example, let's pretend we now have three things:

'Some comment that explains what this variable is
BEFilePath

vs.

BEFilePath

vs.

App.BEFilepath


Now instead of going just from bad (BEFilepath) to good (App.BEFilepath), we're adding in a comment, which is even more stuff that takes me away from what I really want to be doing, so it's even worse than the original because I need to switch gears in my head to read about this variable.

Here's the bottom line: if I needed to read that comment, I've got issues elsewhere because the code doesn't support me. If I didn't need to read that comment...? The comment is garbage and should be removed.

This is all about various practices that come together to support a contextual mental environment in which we do our work. It's not just about comments (or not comments), but having comments is an indicator that other things could be in play that would negate the need for comments, and when all of these ridiculous, subtle things come together and we can work without comments in the code, we've reached a pretty phenomenal point in how well we can work and how the codebase actually supports us.

There's projects that I have where it's like I don't even have to think about anything. If I need to change something, I find my starting point and it's like jumping into a flowing river: I just ride the current until I see what I need. This is awesome. Then there's projects where I open it up and sigh and decide if I should refill my coffee before I have to start wading through this mess to find what I need. One of these two projects will inherently be much more saturated with comments than the other (as if the developer (read: me, years ago, likely) felt the need to make up for lack of excellent naming and structured code by putting bandaids over it with comments).


I actually wrote about naming conventions (specifically that two-part module naming that I mentioned) a while back, here: http://www.dymeng.com/techblog/module-naming/
This article goes into the cognitive side of programming and attempts to explain (with some levity) how subtly important it can be to implement these tiny little practices that can have profound differences in how we work with code.


Good lord I've gone on far enough with that... (I'll offer a slow clap here for anyone still bothering to read this)



Regarding segmented code... I do agree with you, and I think I probably wouldn't have segmented that particular chunk from Anders' snippet, but it is at the point where I'd give it a wary eye and think if I have to add much else to you, you're getting split up. The reason here goes back to context and how many things a person can carry in their heads at once (the link on Module Naming from above goes into the reasons - it's the same concept). And I don't necessarily think that the comments within that snippet are terrible and should be banished. If that's the extend of someone's overzealous use of comments (ha!), that's perfectly fine with me given how much better it is than what I usually see.

With that said, a fairly common recurring pattern for complex tasks is that there exists a module with a single public procedure, and that procedure's purpose is simple to call a number of other, smaller procedures in sequence to perform the ultimate task. Anders' code is beginning to shape into that pattern, but not to the point yet where I would feel any burning desire to refactor it accordingly.


And finally, regard shocks. I have no idea what a shock is. But... BUT! This is business-related knowledge, and as such I would expect that the explanation for this (in terms of business use) would be elsewhere than within the code that calculates it. I would also expect that, being a (likely) custom calculation of some sort, it would attempt to be handled at a single re-usable point within the codebase (in it's own context, dare I use the word again), and at that single point, I would find a comment explaining the technical aspect of the calculation to be acceptable. I would prefer to see a single line comment that says "refer to document X.Y.Z for detail", but with a lack of robust documentation, comments would be acceptable per my OCD on the matter. (and further note that I would expect that if I were in charge of this codebase, this is something I'd likely have to learn fairly quickly, and then I would know what a shock is and have no specific need for the comment anymore anyway - that'd be my guess based on other industry specific concepts, anyway - as long as there's a path to the knowledge: single line comments with links to reference get a thumbs up from me).


For the record, I just checked a few of my cleaner, greenfield VBA projects from the past few years (older projects do not apply smile.gif ), and the comment percentages range from 12 to 28%. The greater majority of those comments are from drop-in modules (Lebans', for example, would often comment tons of stuff as documentation to other developers) and not really what I consider to be "working code" in the sense that they're things I'm apt to be programming in the middle of (one example, a class module for a message/notification builder to do the little OS/tray popup thing, has well over 50% comments). I'd guess that as far as code that I write that is not drop-in style "peripheral" code and that is specific to the core functionality of the application (and not counting the three visual indicator lines for my proc anatomy mentioned in a previous thread), I'm probably somewhere around 5% or less.

Cheers,

Posted by: jleach Dec 30 2016, 10:59 PM

It occurs to me that every time I'm writing code and I put go to put a comment in the body of that code, I stop and think wait, do I actually need a comment here?, and most times there's something else I can change that will negate the need for that comment.

Also, I tend to go through cycles. The initial code, up to the "working point" is generally commented. Then I refactor, and it's during that refactoring that I clean things up to the point where comments are no longer required (that's a good indication that the code is refactored sufficiently).

Also... some languages (namely SQL) tend to have a lot more comments. One of my major pet peeves about working with Access/JET/ACE SQL is that I'm unable to store comments in the query. This is mainly attributed to the fact that the language syntax doesn't allow for semantics as well as other languages though.

Posted by: PhilS Dec 31 2016, 09:28 AM

@jleach:

QUOTE
(or, maybe just file this under Unpopular Opinions )

Quite to the contrary! Your comments made my heart sing. - And thumbs up to all of you contributing here. This is the most interesting thread Iíve seen in any forum for quite a long time!

I strive for 0% comments and I guess my actual rate of comment lines is around the 3% mark. When I feel the need to write a comment, I usually feel I failed making my code readable and understandable enough without comments. However, sometimes I just canít figure out how to put that right.

The only valid reason for comments I allow myself is, when there is something quirky going on on the business side of the requirements, which I feel needs mentioning in the code, because otherwise the code will not be comprehensible.

Writing readable (without the need for comments) and solid code is the rationale behind my http://codekabinett.com/rdumps.php?Lang=2&targetDoc=better-VBA-code, but it is still in its infancy, so there is probably not much of interest for you covered there yet.


I donít appreciate comments regarding who changed what, why, and when because I use source code control in all my projects and the who and when will be automatically tracked by SCC. The what can be easily deducted by comparing the previous version of the code with the current one using a diff tool. Only the why needs to be manually entered as check-in-comment. That comment is clearly linked to the actual version of the module and itís state it applies to, so there will not be any obsolete comments lingering around from ancient times cluttering the code. - Small drawback: You need to look at the scc-history of the module to see this comment.

@GroverParkGeorge:
QUOTE
absence of reliable source control for Access

That is something I disagree with obviously. Among other musings about this topic there is this article http://codekabinett.com/rdumps.php?Lang=2&targetDoc=choose-source-code-control-microsoft-access in which I mention several options. (Disclosure: one of them is my own commercial product)

They are all, including my own, not perfect yet. Still, I use SCC for Access my projects for more than 10 years now and I think it is absolutely worth the little extra effort.

IIRC I got some feedback from some of you already at other places. Still, Iím very interested in reasons why you consider the existing solutions for SCC with Access to be insufficient. Especially the "not reliable" remark is something I have difficulties to comprehend.

Well, ok, enough of these shameless plugsÖ ;-)


@jleach:
QUOTE
For VBA, testing frameworks are about as readily available as SCC tools (ok, even less so).

Well, there are some available, like http://accunit.access-codelib.net/, which looks very promising, but I have not tried it yet.

I actually wrote my own tool for unit testing access projects years ago and used it in a couple of smaller projects. I wasnít really content with its handling and usability though and hence abandoned it a long time ago.
I recently used a modified version of http://www.access-im-unternehmen.de/282.0.html (sorry, German only) quite successfully in a bigger project. - I guess, I should publish my extensions to this tool some time. With those enhancements it is pretty usable, I think.

The main problem with automated testing and Access is not the availability of tools, but the fact that one of the core RAD features of Access is to directly glue the user interface to the database. - Unfortunately, both, UI and data, are very hard to test.

So you either have a very, very hard time to use automated tests with Access or you need to create a layer of intermediate logic between UI and DB that allows for easy testing. But in that process you lose, at least partially, one of the main advantages of using Access in the first place.

I wish you all a Happy New Year!

Posted by: GroverParkGeorge Dec 31 2016, 11:15 AM

I think we're talking past one another to a certain extent.

If YOUR consulting business includes projects for large clients, or for your own organization, all of which have a budget for all of the tools you need, and all of the documentation you want, then it would be reasonable to obtain and use things like Source Control tools.

If you are taking on a $5,000 project with an existing Access application for a three person customer shop, it's hard to insist that they should provide those tools for you before you take the project. I'd rather take on such a project with some appropriate comments embedded, than fly in blind, but then, that's been my experience over the years. Or, perhaps, you can afford to turn away such work unless they agree to supply you with a budget for documentation and all the tools you want?

In other words, it is clearly a case, IMO, that one size does not fit all.

Having learned that you provide a source control tool, I guess we can consider that for future use. Thanks. Good to know that.




Posted by: nvogel Dec 31 2016, 11:40 AM

Hi George. Note that the most popular source control systems are free to use (Git, Subversion), so budget alone does not need to be the deciding factor.

Posted by: GroverParkGeorge Dec 31 2016, 11:49 AM

That's a good point, too.

I've discussed various approaches to Source Control with clients over the years. Most of them who are not deeply involved in software development themselves tend to be reluctant to delve into it, though. And that's just a fact of life with smaller consulting clients.

I wonder, too, how well does Git handle Access? I use it with .net projects, but have never tried to do so with Access.

Posted by: jleach Dec 31 2016, 11:53 AM

Access is a terrible at being source controlled: the entire project is packaged into a single binary file, which is pretty much useless as far as source control goes.

Sure, you can check in the whole file and keep some historic notes on it, but that's about the best you'll get out of SCC for Access.

I've spend a lot of hours writing a utility to split an Access project to completely text-based files for better source control (and to rebuild a project from said files, which ultimately supports parallel development on Access). It's not a fun task in the least bit.

Posted by: JonSmith Jan 2 2017, 05:01 AM

Hi guys,

Happy New Year!!

So to continue this conversation. I fully agree that when you fully understand an application and the naming conventions are awesome and the code well written comments aren't really needed too much. However, put yourself in the context of having an application you have never touched before develops an error, the person who wrote the application has left and no-one knows how it works and they want you to fix it.

I have a few choices,
1. Learn the tool, spend a few hours reading the supporting documentation about what the tool does to become familiar with it, then try to look at the code and use the context I've now learned to understand the code. The problem with this is that I now have to spend hours learning context and even then, the context might not help if the code is badly written with poor naming conventions, in the real life example it is written badly so likely all my context research will be of limited use and I'll still need to go to option 2.

2. Step through the code line by line and work out what each of it is doing. Now this is also learning the context but in a different way, rather than reading external documentation I read procedures, work out what they do and slowly build my context.

3. Read code comments, with the kind of error handling I insist on I can narrow down errors to the specific procedure and line, comments can give me the context of what that procedure is supposed to do and combined with a useful error message I can sometimes narrow down the issue instantly and resolve it. I can then forget about this tool and never waste time learning the context of a tool that is badly designed and really something I don't want to be a part of because the more I see of it the more I'd want to correct it.


In the ideal world, where quality is assured your approach makes sense and is great. Unfortunately I have to work either with developers who are less skilled and wouldn't understand some of the code written or write bad code themselves which I then need to understand.

In terms of external documentation aswell, in my experience its been very easy to let that get out of date versus code comments. With code comments you can change them in the moment as the code changes, external documents often are an afterthought and go out of sync. I like my external documentation to explain the purpose of a tool and any important business concepts and include a userguide. The code then deals with the specifics of any particular task.

I have found this method to be effective. It perhaps also depends on how you scan code, I look out for the green lines and can skip down filtering out the code lines unless I am at a chunk that is relevant. It sounds like you find the green lines distracting? I guess you could always change the font colors in a commented project so they match the background!!!

Posted by: jleach Jan 2 2017, 09:43 AM

We agree on some points smile.gif

For a good project, comments should generally not be required. This makes the assumption that there's a higher level documentation system and that the developer has been at least lightly briefed on the task with sufficient background information for the task. With a well managed project, a developer should not start working with actual code until the context programming task - including why and how (at a slightly higher-than-code level) - are fully established. This should come from somewhere other than the code itself: good documentation, good prepping of the developer to the task on hand.

This of course is in a perfect world, and while it would be nice that all projects are like this, it's certainly not the case in the real world.

To get off topic a hair: the level of failed software projects in our industry is insane. Depending on which reports you read, you can pull numbers such as 65% of all software/IT undertakes are ultimately considered failures (I've actually seen some reports cite numbers in the 70% range)... this is crazy to me: imagine any other industry with such a terrible rate of success... imagine 50% of construction projects as failures (and don't worry about that elevator going up to the 99th floor!). The reasons for these dismal rates are many, but a very large portion of that stems from project management and communication: relatively little of it is in software construction itself (where it is in software construction, it tends to be spread among the maintainability and extensibility aspects (and to a somewhat lesser degree, scalability)).

In any case, given an industry where more than half of project undertakings are failures, it's reasonable (though not heartwarming) to imagine that out of the successful ones, painfully few enough are actually, really GOOD projects.

So, the amount of times that I can rely on things being in place well enough for me not to have to rely on code comments is not very high. (I tend to wonder how many developers have worked through their career without having actually been on a superb project)

With that said, I'll happily agree that given a less-than-stellar project, code comments can be of use for the various reasons described throughout the thread.

I do, however, feel that we should set our goals to perfection and work to achieve that, as opposed to using less-than-best practices and calling it good (granted, "perfection" is extremely difficult to obtain and can take years of personal process defining, while during that meantime we may well have to use less than best practices or accept less than perfect results, which is fine, as long as we're knowing and working towards improving towards that end goal). This is my drive when I make statements such as "comments are bad". Not that we should never have to deal with them and not that it shouldn't be part of our day in day out stuff as programmers (and not even that they aren't helpful), but that we should be striving to reach a level of mastery of our craft that allows us to get away from them.

(In a thread a few months back (I think), we (Jon and I) and another member had a similar style discussion concerning querying/reporting where I made a controversial statement along the lines of "you should never have to ______ (whatever _____ was, I don't recall anymore), and this was very much the same thing... like comments: it's out there, we have to deal with it, but it should be our end-goal to have such a system where we don't have to deal with it anymore, because at that point we've reached the apex of true software development quality).


In the meantime, comments can help get the job done thumbup.gif

(and Happy New Year to all as well!)

Posted by: PhilS Jan 3 2017, 03:15 PM

QUOTE
If YOUR consulting business includes projects for large clients, or for your own organization, all of which have a budget for all of the tools you need, and all of the documentation you want, then it would be reasonable to obtain and use things like Source Control tools.

If you are taking on a $5,000 project with an existing Access application for a three person customer shop, it's hard to insist that they should provide those tools for you before you take the project.

QUOTE
I've discussed various approaches to Source Control with clients over the years. Most of them who are not deeply involved in software development themselves tend to be reluctant to delve into it, though. And that's just a fact of life with smaller consulting clients.


George, thank you very much for these comments. Looking at your objections per se they are sensible, valid, and a strong argument against SCC in smaller projects.

However, I use a totally different approach to introduce source code control at my clients and, if I havenít misunderstood the objections, this approach might weaken their argument.

When I started to write this answer earlier, it got pretty long, so I turned it into a http://blog.ivercy.com/post/tell-clients-about-scource-code-control. I reduced my answer here to a shorter summary:

I do not talk to clients about source code control at all. (Unless they got developers employed themselves, who are going to work with me on the project at hand.)

Iíve got all the required tools licensed to my name. So I do not need to discuss licensing with the client. If I work on a project from my office then the client will never be in contact with SCC in any way.

If Iím required to work at the clientís location I only request permission to install local/client tools on their dev computer and to access my (SCC)-server via the internet. Most source code control systems can have their backend installed in the cloud. So there is no need for installation of the full system at the clientís site.


Now, letís look at actual cost.

I use http://sourcegear.com/vault/ for version control. Assuming you are a small dev shop with 5 users, the initial licensing cost of Vault will set you back $1,700 with another $450 on top for a 5 user Ivercy license. Sure, if you now look at the profit from a $5,000 project, the cost of using SCC is ridiculous.

But itís you, the dev shop licensing the SCC software. You will have another project and another after that. If you break down the cost over a longer time youíll arrive at a price of ~$10 per user per month, even if you pay for (optional!) support and upgrades for both products.

There are other source code control systems around like https://www.microsoft.com/en-us/download/details.aspx?id=48259 or the already mentioned Subversion and Git, which are available free of charge. For Access integration there are some open source tools available as well or, as Jack mentioned, you can roll your own.

So, you can use SCC without spending a penny.


[Edit/Amendment]
There is one very valid point in your objections, which I overlooked until now.

If you are responsible for the project long term and/or you do not care much about the time after, then all the above is IMO a valid argument for rather using SCC instead of including ďhistory-informationĒ in the comments.

But, if you care for the maintainability of the project after you left it, you might be right involving the client more into the process.

Unfortunately there is no usable data-exchange format for SCC-History between different SCC-Systems. So if you are using your own SCC-System and deliver only the completed solution to the client, as I suggested, the client will not have the history of the project available. Any developer working on that later will have to do so without it.

Is this a valid reason to not use SCC? - No, I donít think so. The benefits of source code control are still overwhelming in my opinion.

Is it a reason to include more comments in your code? - Maybe yes. A good solution in my view would be some tool that automatically includes information from the scc-system into the code comments, to hand over that version of the code to the client. (In addition to the lean version.)

Posted by: jleach Jan 4 2017, 12:00 PM

Source control is one of those things where if you're self-taught or hadn't used it to start, you start using it and wonder how you ever managed to live without it. It's the single best non-programming programming practice ever to come about, IMO, and I couldn't imagine doing a project without it. And aside from the initial learning curve, it costs near to zero overhead to implement into your standard process (in fact, due to the inherent backups it makes, I might even argue that it saves you time from a non-source controlled method). In services: git is free, github is free for public use and bitbucket is free for private repositories up to X users or so. The only thing you have to invest is the time to learn the basics and settle into a good git workflow.

Except for Access, that is.

Access has never been well-controlled in terms of source control. The official solutions that there used to be are dropped, and 3rd party/open source solutions either don't cover everything they should, or they don't cover older versions, or there's some other issue with them that makes them less-than-idea to use (even the good ones feel like trying to pin a flower on a bear, at least compared to real source control). Phil has his own that he sells as a product (though I much prefer a CLI-base without cluttering up the UI). I've rolled my own, but it requires a lot of configuration depending on version and various characteristics of the project and doesn't have support for older versions without putting more time into it.

I know very few people who routinely use source control with Access. On the flip side, I know very few people who don't use source control outside of Access.

Oh well, that's how it goes...