Re: [U2] Program Comments/Documentation/Notes/Revision History
By the way, if you use Edit Plus it can fold code based on indent. A little more primative than VS but can be useful anyway. From: u2-users-boun...@listserver.u2ug.org on behalf of Tony G Sent: Sat 27/06/2009 08:26 To: u2-users@listserver.u2ug.org Subject: Re: [U2] Program Comments/Documentation/Notes/Revision History From: David A. Green I've always commented my program at the beginning, but some programs have many changes and when we have 300+ lines of comments it gets a little tedious to deal with embedded in the source code. I'm think of placing them in an external file and then doing a $INSERT in the source code in order to tie them together. How do you handle the long comments? I've often thought of this as being a problem with both the language and the editors that we commonly use. Typical MV editors show all code. There is no provision for folding content or outlining. For example, in C# we can do this: #region Initialization // lots of comment lines here // variable definitions, code, etc #endregion In Visual Studio that collapses to a single line: +Initialization We can click the plus sign to open it up and see the entire section. Other editors support this feature for different languages. Code can be nested: #region Main Section #region Define Variables // definitions here #endregion vars #region Major Function 1 // code here #endregion functions #endregion main Again, that collapses to something like this: #region Main Section + Define Variables + Major Function 1 + Major Function 2 #endregion main Or collapses entirely to: + Main Section But with MV BASIC the language doesn't support this unless we use a pre-processor, and even then we don't have editors that recognize the constructs. The best we can do is to use something like this: *!+ This starts a region * code here *!- This ends the region But then we need an editor to support it. And that brings me to... a minor rant I was writing a new MV Editor to support this and many other features highly desirable to MV developers. But as with many projects where people would inevitably demand a free solution I decided to put this project on the shelf indefinitely. It's just not worth it to try to improve our lot here. Since people are so fond of open source freeware I'll suggest that the source code is available for people to enhance to recognize code as defined above. That's the spirit of open source - we're supposed to give as much as take. If no one wants to enhance one of the fine FOSS utilities out there, then it seems we'll simply never have the functionality. People all too often confuse free=liberty with free=beer. They want the software to be free-of-charge but we rarely see people publishing MV-specific enhancements to open source code as a contribution to the community. It's this condition that causes us to continually lose sites to the mainstream world as people wonder why our development practices are so primitive. C'est la vie. / Tony Gravagno Nebula Research and Development TG@ remove.pleaseNebula-RnD.com ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users ** This email message and any files transmitted with it are confidential and intended solely for the use of addressed recipient(s). If you have received this communication in error, please reply to this e-mail to notify the sender of its incorrect delivery and then delete it and your reply. It is your responsibility to check this email and any attachments for viruses and defects before opening or sending them on. Spotless collects information about you to provide and market our services. For information about use, disclosure and access, see our privacy policy at http://www.spotless.com.au Please consider our environment before printing this email. ** ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users
Re: [U2] Program Comments/Documentation/Notes/Revision History
David I have an auto-doc style of comment that defines what the program does, and version stamps that are compiled into the object code that include a short description alongside other information, similar to the Windows version resource. But I would suggest that modification logs really belong outside the source code and should be in your source code control system (e.g. subversion). That way, you can match the modification log with fetching the actual versions of the source code as it was at that point, and use the tools provided (e.g. TortoiseSVN) to do visual diffs across versions if you need to see what changed. Regards Brian -Original Message- From: u2-users-boun...@listserver.u2ug.org [mailto:u2-users-boun...@listserver.u2ug.org] On Behalf Of David A. Green Sent: 26 June 2009 17:50 To: 'U2 Users List' Subject: [U2] Program Comments/Documentation/Notes/Revision History I've always commented my program at the beginning, but some programs have many changes and when we have 300+ lines of comments it gets a little tedious to deal with embedded in the source code. I'm think of placing them in an external file and then doing a $INSERT in the source code in order to tie them together. How do you handle the long comments? Thanks, David A. Green www.dagconsulting.com (480) 813-1725 ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users
Re: [U2] Program Comments/Documentation/Notes/Revision History
Another option is to have an accompanying wiki/vcs setup where a lot of metadata about why and what can be stored outside of the code. With version control, you fight the need to comment out old code and leave it in. And the wiki can be as verbose as you want. ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users
Re: [U2] Program Comments/Documentation/Notes/Revision History
Ross - Your suggestion for folding on syntax is fine but it doesn't go far enough. The mainstream development world recognized what you're saying long ago, did it, and then improved upon it again. We're sort of two generations behind in this discussion. Yes, Visual Studio folds C++, C#, and VB.NET on language structures. NetBeans, Eclipse, and other IDEs fold Java, PHP, and other languages like that too. They all fold comments as described in the OP. But then there is the next step. There is a major difference between folding code exclusively based on syntactical stuctures and folding based on logical/functional components. In BASIC we can have several labelled, internal subroutines, and UV Functions, that are a part of a functional set. But, we can't put those into a block to get them out of our way while we're working on other sections. The way I've done this is by INCLUDING code and then using a utility that imports and exports all included code when I need to see it all in one block or for editing. The mvToolBox editing software from DM Consulting is the only product I know that does this sort of visual hydration and dehydration of code stored in different modules. Your faith in programmers following standards is amusing. There are no standards to be followed here. This is just a function of the development environment, like comments. Use it or don't as it's convenient. Other languages and IDEs support folding and developers use this stuff every day - it's unnatural Not to have it anymore. Err, except for our (n)ever evolving Pick BASIC. Tony Gravagno Nebula Research and Development TG@ remove.pleaseNebula-RnD.com Visit PickWiki.com! Contribute! From:Ross Ferris Whilst I appreciate the structural tags I'd suggest that they are not needed. It doesn't take too much thought to recognise the self-bounding regions Label: -- return For -- next If -- else -- end Loop -- repeat Begin case -- case -- end case There are some funny possibilities with read/locked|then|else Whilst I appreciate the fine grained control your suggestion provides, my faith in programmers generally following this standard is low, and providing people haven't employed a single, linear top-down approach to their programming, I think most (all) of the collapsible regions could be derived directly from the code with minimal effort ___ U2-Users mailing list U2-Users@listserver.u2ug.org http://listserver.u2ug.org/mailman/listinfo/u2-users
