davestewart Posted November 14, 2008 Share Posted November 14, 2008 I wrote a small Flash app last year to help me out with better-organising and navigating my code called Comment Headings, and I've just updated it. It basically allows you to type in section titles and have them be produced as ASCII art style headings, which makes it much easier to navigate scripts, as it's very easy to see what's where. For example: // ------------------------------------------------------------------------------------------------------------------------ // // ██████ ██ ██ ██ ██ ██ ██ ██ // ██ ██ ██ ███ ███ ██ ██ ██ // ██ ██ ████ ██ ██ ██ █████ █████ █████ ███████ █████ █████ █████ █████ █████ █████ // ██████ ██ ██ ██ ██ ██ ██ ██ ██ ██ █ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ // ██ ██ ██ ██ ██ █████ ██ █████ ██ ██ █████ ██ ██ ██ ██ ██ ██ ██ █████ // ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ // ██ ██ ██ ███ █████ ████ █████ ██ ██ █████ ████ ██ ██ █████ █████ █████ // // ------------------------------------------------------------------------------------------------------------------------ // Private Methods private function doSomething() { // function body } private function doSomethingElse() { // function body } // etc It now has options to let you fully customise the input and output using an XML preferences file. For example, you could set up different input headings (Variables, Methods, Initialize, etc) depending on whether you were building class or page code, or you could set up different comment delimiters depending on whether you were coding PHP or VB or something else. If you're using something like Eclipse, then it may not be as useful, but if organising code in a more basic editor, I find I can't work without it now! Test, use, and download it from here: http://www.keyframesandcode.com/code/development/comment-headings/ Cheers, Dave Link to comment Share on other sites More sharing options...
nadeemshafi9 Posted November 14, 2008 Share Posted November 14, 2008 nice Link to comment Share on other sites More sharing options...
JonnoTheDev Posted November 14, 2008 Share Posted November 14, 2008 Not sure how this would really help. Just huge headings. Doesn't display what the methods, variables do, return etc. Access levels of methods, member variables are easily read with the public, protected, private syntax. Class commenting should look as follows: /** * Available frontends * * @var array $availableFrontends array of frontend name (string) */ public static $availableFrontends = array('Core', 'Output', 'Class', 'File', 'Function', 'Page'); /** * Factory * * @param string $frontend frontend name * @param string $backend backend name * @param array $frontendOptions associative array of options for the corresponding frontend constructor * @param array $backendOptions associative array of options for the corresponding backend constructor */ public static function factory($frontend, $backend, $frontendOptions = array(), $backendOptions = array()) { Link to comment Share on other sites More sharing options...
davestewart Posted November 14, 2008 Author Share Posted November 14, 2008 Hi Neil, It's certainly not supposed to replace JavaDoc commenting, or any other documentation for that matter! All it is, is a large visual reference to areas of your script, so when you're scrolling through large (or even small) scripts you can immediately tell which section you're in. The point is with simple characters -, =, * etc, there's only so much emphasis you can make to a heading, and it's often a lot of legwork. This is just a tool to make that easier. You don't have to stick to headings like "Private Methods", you could have "Front end", "File tasks", "Notes", whatever you like. Link to comment Share on other sites More sharing options...
nadeemshafi9 Posted November 15, 2008 Share Posted November 15, 2008 will it affect sending headers ? Link to comment Share on other sites More sharing options...
davestewart Posted November 15, 2008 Author Share Posted November 15, 2008 I thought it might be helpful to briefly show the comparison between a comment-headered file and a normal file, and how it's easier to skim through the one with comment headings: A file with comment headings. A file with normal text-based headings. And no, it doesn't affect headers. Link to comment Share on other sites More sharing options...
nadeemshafi9 Posted November 17, 2008 Share Posted November 17, 2008 I thought it might be helpful to briefly show the comparison between a comment-headered file and a normal file, and how it's easier to skim through the one with comment headings: A file with comment headings. A file with normal text-based headings. And no, it doesn't affect headers. my man, your headings dont work on a MAC in firefox, i think its cos the character is not standard Link to comment Share on other sites More sharing options...
davestewart Posted November 17, 2008 Author Share Posted November 17, 2008 Yeah I know. It's not happy in FF3 on a PC either, but it's fine inside an IDE! Link to comment Share on other sites More sharing options...
Mchl Posted November 17, 2008 Share Posted November 17, 2008 I think I could use it for my ExtJS JavaScript files... They tend to get bigger and bigger... Link to comment Share on other sites More sharing options...
waynewex Posted November 18, 2008 Share Posted November 18, 2008 Man, some of my class files are nearly 1500 lines long. Link to comment Share on other sites More sharing options...
Mchl Posted November 18, 2008 Share Posted November 18, 2008 That is not really large, although I try to stay below 1000 per file. Sometimes it's not possible though. I'm now working on a GUI that hasn't got a fourth of it's planned functionality yet, and is already over 1000 lines. This will be a hog and I'm thinking of a way to split it somehow. Link to comment Share on other sites More sharing options...
davestewart Posted November 18, 2008 Author Share Posted November 18, 2008 Glad you guys might find it useful. I'll be making another update in a week or so, with a method to use your own custom fonts, so check back then... Link to comment Share on other sites More sharing options...
davestewart Posted November 19, 2008 Author Share Posted November 19, 2008 OK - final update to the app: I've now added a selection of 12 custom fonts, of varying sizes and styles, full punctuation and European character set for most of them. http://www.keyframesandcode.com/code/development/comment-headings/ I can't really see it needing anything else, so I think that's it for now. Enjoy! Link to comment Share on other sites More sharing options...
BoltZ Posted November 21, 2008 Share Posted November 21, 2008 nice but won't this super large text slow page load times? Link to comment Share on other sites More sharing options...
Mchl Posted November 21, 2008 Share Posted November 21, 2008 When in PHP? Nope. When in JavaScript? Yes they will. Link to comment Share on other sites More sharing options...
BoltZ Posted November 21, 2008 Share Posted November 21, 2008 Hm I guess he will have to answer what it is. PS. Congrats on 1400 posts Link to comment Share on other sites More sharing options...
darkfreaks Posted November 22, 2008 Share Posted November 22, 2008 hey might want to use functions like mysql_real_escape_string(),trim(),strip_tags(),htmlspecialchars() to make sure you cant enter html special characters or MYSQL statements into the database that could execute Link to comment Share on other sites More sharing options...
Mchl Posted November 22, 2008 Share Posted November 22, 2008 Just what script in this topic uses MySQL? Link to comment Share on other sites More sharing options...
Recommended Posts