UtterAccess.com
X   Site Message
(Message will auto close in 2 seconds)

Welcome to UtterAccess! Please ( Login   or   Register )

Custom Search
> Comments To Code Percentage, Any Version    
 
   
JonSmith
post Dec 30 2016, 06:01 AM
Post#1



Posts: 3,098
Joined: 19-October 10



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
Go to the top of the page
 
Start new topic
Replies
GroverParkGeorge
post Dec 30 2016, 07:58 AM
Post#2


UA Admin
Posts: 30,461
Joined: 20-June 02
From: Newcastle, WA


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.

--------------------
Go to the top of the page
 
jleach
post Dec 30 2016, 08:52 AM
Post#3


UtterAccess Editor
Posts: 9,745
Joined: 7-December 09
From: Staten Island, NY, USA


>> 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,

--------------------
Go to the top of the page
 
GroverParkGeorge
post Dec 30 2016, 09:07 AM
Post#4


UA Admin
Posts: 30,461
Joined: 20-June 02
From: Newcastle, WA


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.


.
This post has been edited by GroverParkGeorge: Dec 30 2016, 09:09 AM

--------------------
Go to the top of the page
 
jleach
post Dec 30 2016, 09:18 AM
Post#5


UtterAccess Editor
Posts: 9,745
Joined: 7-December 09
From: Staten Island, NY, USA


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,

--------------------
Go to the top of the page
 
GroverParkGeorge
post Dec 30 2016, 09:21 AM
Post#6


UA Admin
Posts: 30,461
Joined: 20-June 02
From: Newcastle, WA


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".

--------------------
Go to the top of the page
 
Doug Steele
post Dec 30 2016, 09:31 AM
Post#7


UtterAccess VIP
Posts: 21,312
Joined: 8-January 07
From: St. Catharines, ON (Canada)


You might be interested in a column my friend Peter Vogel (former editor at Smart Access) wrote a few years ago, entitled Why You Shouldn't Comment (or Document) Code. Follow the links at the top of the article too.

--------------------
Go to the top of the page
 
jleach
post Dec 30 2016, 09:58 AM
Post#8


UtterAccess Editor
Posts: 9,745
Joined: 7-December 09
From: Staten Island, NY, USA


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))

--------------------
Go to the top of the page
 
PhilS
post Dec 31 2016, 09:28 AM
Post#9



Posts: 363
Joined: 26-May 15
From: The middle of Germany


@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 Better VBA video series, 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 on SCC for 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 AccUnit, 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 accessUnit (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!
This post has been edited by PhilS: Dec 31 2016, 09:30 AM

--------------------
The shocking revelation about digital signatures for accdb files.
Go to the top of the page
 
GroverParkGeorge
post Dec 31 2016, 11:15 AM
Post#10


UA Admin
Posts: 30,461
Joined: 20-June 02
From: Newcastle, WA


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.




--------------------
Go to the top of the page
 
nvogel
post Dec 31 2016, 11:40 AM
Post#11



Posts: 776
Joined: 26-January 14
From: London, UK


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.
Go to the top of the page
 
GroverParkGeorge
post Dec 31 2016, 11:49 AM
Post#12


UA Admin
Posts: 30,461
Joined: 20-June 02
From: Newcastle, WA


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.

--------------------
Go to the top of the page
 

Posts in this topic
- JonSmith   Comments To Code Percentage   Dec 30 2016, 06:01 AM
- - Marsupilami72   I just did a quick count on the routine i am curre...   Dec 30 2016, 06:14 AM
|- - Jeff B.   One reason for including comments in code is to he...   Dec 30 2016, 07:10 AM
- - GroverParkGeorge   I just checked one project on which I am at least ...   Dec 30 2016, 07:58 AM
|- - nvogel   I don't think there's any "right...   Dec 30 2016, 08:50 AM
|- - jleach   >> Obviously 2% is waaay too low << W...   Dec 30 2016, 08:52 AM
|- - GroverParkGeorge   While I don't disagree with most of your comme...   Dec 30 2016, 09:07 AM
|- - jleach   Yea, lack of good SCC in Access makes revisions a ...   Dec 30 2016, 09:18 AM
|- - GroverParkGeorge   Well, there's that pesky budget problem to man...   Dec 30 2016, 09:21 AM
|- - Doug Steele   You might be interested in a column my friend Pete...   Dec 30 2016, 09:31 AM
|- - GroverParkGeorge   Hmm. Thanks, Doug. Sometimes I tend to lose perspe...   Dec 30 2016, 09:50 AM
|- - jleach   Good article(s) Doug, they better articulate my po...   Dec 30 2016, 09:58 AM
|- - JonSmith   Nice to see its caused some discussion!! ...   Dec 30 2016, 02:00 PM
||- - JonSmith   To put it another way, I agree that if code is of ...   Dec 30 2016, 02:06 PM
||- - jleach   I have worked with many other people's VBA cod...   Dec 30 2016, 02:44 PM
||- - jleach   (as you might have guessed, I'm very OCD about...   Dec 30 2016, 02:53 PM
||- - TheSmileyCoder   I took over a project which had plenty of comments...   Dec 30 2016, 04:49 PM
||- - jleach   I might even go so far as to break down each task ...   Dec 30 2016, 05:46 PM
||- - JonSmith   Interesting thoughts Jack. I fear you are thinkin...   Dec 30 2016, 06:28 PM
||- - jleach   Hi Jon - no fear, I have an explanation for everyt...   Dec 30 2016, 10:29 PM
||- - jleach   It occurs to me that every time I'm writing co...   Dec 30 2016, 10:59 PM
|- - PhilS   @jleach: QUOTE (or, maybe just file this under Unp...   Dec 31 2016, 09:28 AM
|- - GroverParkGeorge   I think we're talking past one another to a ce...   Dec 31 2016, 11:15 AM
|- - nvogel   Hi George. Note that the most popular source contr...   Dec 31 2016, 11:40 AM
|- - GroverParkGeorge   That's a good point, too. I've discussed ...   Dec 31 2016, 11:49 AM
|- - jleach   Access is a terrible at being source controlled: t...   Dec 31 2016, 11:53 AM
||- - JonSmith   Hi guys, Happy New Year!! So to continue...   Jan 2 2017, 05:01 AM
||- - jleach   We agree on some points For a good project, comm...   Jan 2 2017, 09:43 AM
|- - PhilS   QUOTE If YOUR consulting business includes project...   Jan 3 2017, 03:15 PM
|- - jleach   Source control is one of those things where if you...   Jan 4 2017, 12:00 PM
- - tina t   hi, guys, i really love it when a group of you get...   Dec 30 2016, 07:10 PM



Custom Search
RSSSearch   Top   Lo-Fi    22nd September 2017 - 03:43 PM