| Author |
 Topic  |
|
addbo
Starting Member
Canada
9 Posts |
 Posted - 26 November 2002 : 12:15:35
|
I've just gone through the process of installing the "Universal Login" mod... and even though the readme for that mod marked it as an easy install (1 on a scale of 1 to 10) I definitely had problems with it... having to actually go in and modify the inc_header.asp file (well copy it then modify the copied version) for it to work...
Looking through several ASP pages I've noticed that there is little OR no documentation in the code itself so basically one has to guess and go through the code very thoroughly to understand what one can modify or delete... and what code is essential for use...
Even if each ASP page just had a header that kind of described what that page did (the filename itself is descriptive but gets ambiguous if one is looking at things like "admin_login", "admin_login_short" ... what does admin login do? How about the short? or how about "admin_login", "admin_login_short", "login", "setup_login" and now with my "inc_login" (after the universal login mod)) That would be extremely helpful to newbie developers... but of course more extensive documentation would make life even easier for new developers...
Anyways just a suggestion... the forum is great and I would love to contribute sometime later, but understanding the undocumented code might take awhile (unless there is a documented version somewhere for developers... and this undocumented one is just for the general masses to decrease bandwidth...)< |
The only Normal people are those you don't know - Joe Ancis |
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 26 November 2002 : 18:26:13
|
yea.. can't realy document the release code caus of size :) but documenting and striping the release version is not a bad idea :)... the trick is figuring out how to actualy accomplish this without jeprodising the code...
I've always used '## to document my notes in code, so it's a definate unique thing instead of just '
Thoughts?< |
Reinsnitz (Mike) |
 |
|
|
addbo
Starting Member
Canada
9 Posts |
Posted - 26 November 2002 : 20:05:46
|
Well I remember writing a program in Comp Sci class that stripped comments from C/C++ code... and that had to handle the // for one line comments and /* */ for multi line comments...
I'm sure it couldn't be too too difficult to write a program that strips comments... especially since VB uses just ' that I can recall for comments... and that ends at the EOL ... one could just parse for the ' character... deleting characters till the EOL is reached.
I'm simplifying of course... one has to make sure it isn't part of something else... or there isn't an escape character \' is not in front of it... but I would think making a comment stripper for ASP pages shouldn't be all that difficult =)
And of course you'd make duplicates of your pages and test to see it works after it has gone through the comment stripper ;) To be extra safe just make sure there is a standard way of coding comments so one can be sure that it is actually stripping the comments properly every time... though the comment stripping program itself should be fairly robust...
I'm guessing there should be one out there somewhere... but if not I'm sure coding one would be quite easy ;)
But yeah I would still like to have a developer version with comments intact for ease of development... just have two packages or something =)< |
The only Normal people are those you don't know - Joe Ancis |
|
|
|
Gremlin
General Help Moderator
New Zealand
7528 Posts |
Posted - 26 November 2002 : 22:13:25
|
| The documentation is here at the forums, youre reading it now :)< |
Kiwihosting.Net - The Forum Hosting Specialists
|
|
|
|
DJBBIZ
Junior Member
214 Posts |
Posted - 28 November 2002 : 13:42:50
|
No documentation does help you learn the code but it does get frustrating sometimes. I would like to point out to the more expert developers and moderators that many of the 1-10 rankings are totally wrong as they are from an expert's standpoint. addbo is totally correct, in order to be a good teacher or instructor you need to be able to get down to their level of comprehension so you know what and how much to feed them. At least in the forum you can ask questions and get responses where one can gage the users level. Documentation on the other hand should always start at the lowest common denominator and build from there. A "1" difficulty level is "copy this new and nonexisting file to the forum directory and you are done". A "2" would be "copy this revised existing file but backup your old one and be careful that you have not modified it previously other wise you will need to manually add this code..." A "3" is "here is the code to look for before and after the file modification and here is the code you need to put into the file". A "4" is "you will have to modify several files with this code..." A "5" is you will need to run a database update to add tables and or fields and modify code. Although the db update is made easy under the admin option, if there is a problem you need to understand what is happenning, if the tables were added, altered...to diagnose your problems. A "6" is all the above and a change to the directory structure and or configuration settings that affect your entire forum performance. Again the idea is like a science experiment in a lab, the more variables you have to change the more chances for errors and the harder to detemine the source of the problem. "A" 7 would be all of the above and changes required to your pc system settings or your db software settings much like you have to prepare when you first install. An "8" would be a changeover requiring not only the above items but having to port over (import/export) data to new db or tables such as in a upgrade between versions may require. A "9" requires knowledge of programming to customize something to your specific situation, db, web host...such as creating a new variable which would need to be put into the certain parts of the code in multiple pages... A "10" is all other monsters that even the moderators and pepole with many years of experience are challenged with...
This is just an example and I am sure the community could come up with even more refined standards, but with no documentation I think documenting a standard policy of rating the difficulty level would help the user determine what he should take on. He can learn with the installation of 1-3 mods first, 4-7 mods and then graduate to 8-10 and making mods.< |
"The difference between good ideas and good results is performance"
the management institute | tmiFinance | tmiCreative | ProfileOnDemand |
|
|
|
laser
Advanced Member
Australia
3859 Posts |
Posted - 28 November 2002 : 15:01:56
|
Even a documentation forum would be a start (we have one at work  ). We have a system that was built with relatively no documentation, but now we have to know how it works in order to add/change/delete features. So the rule is, if you touch it, you document it. Every function has it's own thread, containing syntax, arguments, returned values, etc.... It ends up being an encyclopedia (fully searchable of course) of the system - built up by the people that need it.
We could do the same thing here, members can document blocks of code, functions, variable use, etc... as they need and for the benefit of everyone else. I might be wrong, but that's a bit more community-minded than the current : you ask the questions and we'll supply the answers. MOD builders are probably the best to do this, because they are ripping apart the code, that's if the DEV team doesn't want to do it.
Myself ?? well, I would only be a user at the moment, but I can see myself helping out as I learn more about the code in Snitz< |
|
|
|
jkmcgrath
Junior Member
USA
145 Posts |
Posted - 28 November 2002 : 17:16:58
|
Yes this is what I have been waiting for!  < |
Delta Force Seals |
|
|
|
davemaxwell
Access 2000 Support Moderator
USA
3020 Posts |
Posted - 28 November 2002 : 21:11:41
|
| Davio started this kind of function, but it never seemed to get off the ground. Perhaps someone could take this and run with it. Do a search of the forums and you should be able to find the info you need.< |
Dave Maxwell
Barbershop Harmony Freak |
|
|
|
Davio
Development Team Member
Jamaica
12217 Posts |
Posted - 29 November 2002 : 17:12:12
|
What are you reffering to Dave? The MOD Document I was working on?
If so, I am still working on it. Little by little. Since I don't have much help, it's taking a while to finish. But I will finish it.< |
Support Snitz Forums
|
|
|
|
addbo
Starting Member
Canada
9 Posts |
Posted - 03 December 2002 : 13:41:35
|
heh, maybe we can make a man page like the OpenBSD... I guess that might be another project in and of itself...
As for the suggestion that this forum is the documentation... that is nice if you have a specific portion of code that you're asking about "what does x function do?"... but I think that could get tedious for those answering the questions if everyone starts asking about each little function or piece of code that goes into the workings of the forum... I'm of the mind that we document it once... then add/edit later... (and the forum is the secondary source when we don't exactly understand the comments in the code... but at least it gives us the ability to say RTFM first... heh)
Some other things I wouldn't mind seeing... an entity relationship diagram for the DB so I can see which fields relate to whom... I don't see any connections in the DB itself (at least the Access DB included with the forum)... I understand that most of the integrity rules must be enforced by the code itself... though I find that kinda scary... Also documentation of the DB itself... what each table stores... (though mostly self explanatory... still)... what each field stores and is used for... foriegn keys if any... etc.
Anyways this is just a wishlist seeing as it's almost christmas =P I believe it would make developing for this forum a bit easier... and might make maintaining it easier as well in the long run... but then again what do I know? 
It does seem there is a "market" for this documentation... at least from the comments above...< |
The only Normal people are those you don't know - Joe Ancis |
|
|
|
davemaxwell
Access 2000 Support Moderator
USA
3020 Posts |
Posted - 03 December 2002 : 14:08:20
|
quote:
Originally posted by Davio
What are you reffering to Dave? The MOD Document I was working on?
If so, I am still working on it. Little by little. Since I don't have much help, it's taking a while to finish. But I will finish it.
I think that's the one I'm talking about. Where the functions/subs are documented (parameters, etc). That was you, right???< |
Dave Maxwell
Barbershop Harmony Freak |
|
|
|
Davio
Development Team Member
Jamaica
12217 Posts |
Posted - 03 December 2002 : 16:23:36
|
Yep. I just take a few minutes each day and work on it bit by bit.
addbo, most of what you asking for is what is going into the document I am working on. Defining each function and subroutine used in the forum and defining each table and fields used in the database. Along with some info on setting up mods and hopefully a guideline to creating mods.
Lots of work, which I am determined to finish. But it's going slowly, so don't expect it for christmas. Of course if you want to lend a hand, just send me an email and we can talk some more. I already have a template up if you are instrested in looking at it.< |
Support Snitz Forums
|
|
|
|
Reinsnitz
Snitz Forums Admin
USA
3545 Posts |
Posted - 05 December 2002 : 18:53:29
|
Um... this forum exists... and it never got flying... we have always had enouph people who want it, but as this is a volunteer project, we have never had anyone "Volunteer" to do the work that has been able to take the time needed to accomplish the task! :)
http://forum.snitz.com/forum/default.asp?CAT_ID=14< |
Reinsnitz (Mike) |
|
|
|
snaayk
Senior Member
USA
1061 Posts |
Posted - 06 December 2002 : 08:23:33
|
This comes up every now and then and then it fades into the background. Then a few months later, someone brings it up again and the thread starts anew. Perhaps what is needed is for a clear outline of what is needed. In the proper forum, The DOCs one for example. Figure out what is needed and what the goal is in that particular area and then hopefully get volunteers to work on it. Then Assign 2 (or more) individuals (probably moderarators or promote someone) to oversee the entire DOC projects. SInce all elements will have to alike to privide a real DOC to this projects.
Its definately needed. I think this will also perhaps identify areas where improvement can be made in the code in the future. Things one might stumble over while documenting code.
< |
|
|
|
Davio
Development Team Member
Jamaica
12217 Posts |
Posted - 06 December 2002 : 11:48:47
|
Not many users are willing to spend a lot of time into taking on a project like this. They just don't have time. Since I have started the MOD Document I have invited others to work with me in getting it done. The most I have gotten is basically information to put into the document. Which I am thankful for. But there is more to be done.
I have already said that I will complete the manual. It's going slowly as I work on it bit by bit, but I am determined to finish it. If anyone wants to see it done faster or willing to help out you can just drop me an email.
I have seen members just come by say that a document or manual is needed. I say I am working on it you can help if you want. But usually they don't want to. Or they have a whole new idea and want to start something new. Or they say they would love to help, but you don't hear anything from them. Or they don't have any experience to writng a doc. After that I just wait until someone else voice that a manual is needed and see if they are willing to help.
But regardless, I am determined to finish it. Hopefully it will be a stepping stone for other documents/manuals to come along.< |
Support Snitz Forums
|
|
|
|
botNET
Starting Member
33 Posts |
Posted - 09 January 2003 : 14:31:39
|
To help documenting this code, you REALLY need to know what is happening, all relations between variables/methods/dbtables etc, etc, etc.
The most time consuming is to "read" all undocumented code and then understand the code. ITīs really hard, even for an "expert" who is working as a webdeveloper, due to how big this application is.
Speaking for myself, working as a proffessional webdeveloper in asp/vb/mysql/ms-sql/asp.net(vb) and LotusNotes, I donīt have time to go through all code, trying to understand it, and THEN document the code .... but, the documentation is really needed and should have been their from the beginning.
just my 0.002
< |
|
|
|
Topic |
|
Forum Locked
