| Author |
 Topic  |
|
|
e3stone
Average Member
USA
885 Posts |
 Posted - 31 July 2002 : 13:58:29
|
I was toying with methods to comment the code that would make it slightly easy for new members to understand the code. Here's one method that I'm trying, but I wanted your opinions of whether or not this makes the code easier or more difficult to read.
http://www.insidewaco.com/default.txt
I was also thinking about just making an index for each page which has a list of all variables, function, procedures, etc, something sort of like what's done in the IBuySpyPortal application (for those of you who have seen that)
I realize that documentation has been discussed, discussed, and discussed again...this method might have already been brought up and addressed.
If this method that I'm using sucks, in your opinion, let me know. I'm not sure if we've standardized documentation/comment methods as of yet.
I'm wondering whether or not I should just wait until 3.4 is released before I dive straight into doing this.
on a side note: you might notice that there's a if..then statement right above one of the queries that checks the variable intUseStoredProcedures. Well, I thought of this last night as a way to keep the queries as they are currently (for Access) and then be able to switch to SQL Server and use Stored Procedures. Don't know if this idea has been addressed, either.
Let me know what you think on both of these issues.
<-- Eric -->< |
|
|
Deleted
deleted
4116 Posts |
Posted - 31 July 2002 : 15:17:46
|
Two things:
1. The new v3.4 code is using "& _" constructs at the line ends (especially response write's and spanning a lot of lines), so dividing it will be impossible without changing it.
2. So much comments will degrade the performance unnecessarily. These comments cannot stay in the final release.
3. We call it "Programmers (Technical) Manual". This is what we need. It has to include all global vars, publicly usable procedures/functions with all the parameters.
Here is an example:
' Function fLangN(s: string, paramlist)
' Used for sentences which are mixed with variables from code. Parameters are parsed and inserted
' into the sentence. The places of insertion are defined in the value of the string as %sN% where N
' (1,2,3...) indicates the variable
' INPUT
' ==== s: String of language variable name ==== changed for IIS4 compatibility
' s: String (language variable)
' paramlist: String, Separeted list of variable values. The format is : "param1|param2|..."
' where | is used as separetor. ParamN is used to replace variable %sN%.
' EXAMPLE
' ==== response.write fLangN("strLangDefault00060", intNoOfRecords & "|" & intMaxRecords) ==== changed for IIS4 compatibility
' response.write fLangN(strLangDefault00060, intNoOfRecords & "|" & intMaxRecords)
'
function fLangN(s, paramlist)
DIM s1, strParamArr, N, i
' s=eval(s) ' commented out for IIS 4 compatibility, all related function calls changed
s1 = s
strParamArr = split(paramlist, "|")
N=ubound(strParamArr)
for i=0 to N
s1=replace(s1,"%s" & i+1 & "%",strParamArr(i))
next
fLangN=s1
end function
And this will stay in another file, not the executed .ASP file...
This is just the starting point. It must need versioning, file info easy access methods, etc.
These functions/global vars etc change in time (deleted, added, modified, parameters change, divided, re-collected). Documentation is an important stage in SW Engineering and it is hard to keep with the development/maintanence stages...
Think Pink
==> Start Internationalization Here< |
 |
|
|
e3stone
Average Member
USA
885 Posts |
Posted - 31 July 2002 : 17:04:58
|
What about using something like Microsoft Help Workshop to create an indexed/Table of Contents and Search Help Document? I'd be willing to take a break from doing any "coding" for a while and work with someone on creating one of these. I think this would be an ideal Help/Documentation idea. Easily updated, too.
<-- Eric -->< |
|
|
|
Gremlin
General Help Moderator
New Zealand
7528 Posts |
Posted - 01 August 2002 : 09:12:59
|
quote:
2. So much comments will degrade the performance unnecessarily. These comments cannot stay in the final release.
True only for ASP2.0, 3+ the code is precompiled before execution and only recompiled if its been updated I believe.
www.daoc-halo.com< |
|
|
|
Deleted
deleted
4116 Posts |
Posted - 01 August 2002 : 16:24:01
|
Well, I think an HTML based solution is much better as it will run locally, remotely on host, will be client independent etc...
Gremlin, you're right on this.
Think Pink
==> Start Internationalization Here< |
|
|
|
Etymon
Advanced Member
United States
2385 Posts |
Posted - 01 August 2002 : 17:56:54
|
Thanks for bringing this up again e3stone.
I like your idea of a html-based website with a search function.
How about merging a forum for discussion purposes along in with the mix. I'd like to see where a person could ask a question like, "What does str mean?" It would be a place where the search tool could be extensively promoted. I use the search tool much more than I ask questions here at Snitz.
To use a forum for education like this, one would have to really plan the logical layout of it so as to not confuse people. Perhaps a MOD could be created to be used in topic.asp via a radio button or a dropdown menu where a person must choose which version of Snitz their quesion is applying to. It would be nice if search.asp also had this criteria included. This way when someone is doing research on a particular aspect, they can narrow their findings more quickly.
I'd love to see a glossary with comments on how particular aspects of ASP were "meant" to work in Snitz. That would be helpful. Of course, I don't expect security issues to be in open-air discussions, but I think basic security to well-known issues could be addressed.
Just some thoughts.
The comments on your default.txt file do seem to be a bit cumbersome. However, if you are doing a straight .txt file not meant to ever be used for production, then why not take an out-of-the box default.asp, convert it to .txt, and then add line numbers. From there, you can add all the comments you like in a better format ... even save the file in html. Because then you would have the line numbers, but you could also bold, italicize, underline, change font color, or whatever, without effecting the look of the code.
Etymon
Are you looking for answers at Snitz? | Searching the forums is easiest!
Basic | Advanced (Internet Explorer only)< |
|
|
|
Etymon
Advanced Member
United States
2385 Posts |
Posted - 01 August 2002 : 18:06:53
|
Also, I'd like to add something that I would personally find helpful.
Here at work, I can't download any files. I can only view them like in your .txt file and also .htm, .asp, etc. I just can't download files.
It would be great if there were two things:
1) If there was a simple list (.html file) of all the names of the files which come in an out-of-the-box Snitz.
2a) Then it would be very nice if each file was saved (with line numbers) as a .txt file and then linked to the simple list mentioned above.
2b) If a person was feeling very spunky, they could make each file into a .html and then highlight various aspects of the files and have either or both a link to a popup which would define the noted text and perhaps a link to a topic in a forum which is a fine example of an explanation of how it is used in practice.
This way when I am here at work and bored brainless, at least I can review the code I worked on earlier that day at home. Perhaps I was adding a MOD or the like. It just would be a nice study aide.
e3stone, when I can, I'd like to help you on a study site, if you would like the help. If you would just like some ideas or critiques here and there, I understand. 
I think these things may expedite the learning curve of those interested in learning ASP, HTML, VBScript, Javascript, etc. as these technologies are used in the Snitz forums as well as strengthen the base pool of MOD authors here at Snitz.
Cheers,
Etymon
Are you looking for answers at Snitz? | Searching the forums is easiest!
Basic | Advanced (Internet Explorer only)
Edited by - Etymon on 01 August 2002 18:17:13< |
|
|
| |
Topic |
|
|
|
Forum Locked
