10 Replies Latest reply on May 30, 2014 9:42 AM by KonTiki

    CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .

    KonTiki

      I doubt if I'm the only one thinking of this but here goes.

       

      Often when coding an app in an area that needs some prior analysis and math, it's wise to detail in the code's comments just how and why the code is written as it is. Without this info written down, it's hard to get a handle on things a few months - and a few projects ! - after.

       

      But lengthy comments disrupt the amount of code that's visible in one screenfull.

      And since source files are little more than text files, you can't put in things like math equations, UML diagrams, circuit diagrams, schematics, orientation arrows, etc without a ridiculous amount of fiddling - e.g. putting numerator, line and divisor on separate lines.

       

      I think what is really needed here is a separate file type that can accommodate equation writing, UML diagrams, circuit diagrams, schematics, etc and which the person examining the code can open on a separate window on their large monitor when they needs to find the computation method used in a project.

       

      Sure, the odd small comment will still be needed within the code but these would now be simply reference points between the code and the info file once the latter has been read and digested.

       

      I've tried searching under "code info(rmation) file" to no avail on Google.

       

      Does anyone else know of any existing file structure that would be incorporatable into projects for the purpose I've described ?

      And preferably compatible with the needs of all the major coding languages (i.e. Java, C/C++/C#/Obj C, Ada, Ruby) and their common IDEs.

        • 1. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
          skytrace

          If talking about Java. Do you not want to create some .html docs by using javadoc tool and describe algorythm, UML diagrams etc. in there? For example: For basic describing of methods, classes, interfaces you can use a javadoc tool, and also you can to provide extenstion for make UML diagrams, math formulas in html file. You just need try to do this with document made by javadoc, you need try modify that .html files, add a simple diagram, and see how it should be.

          For example:

          You have a class MyMathClass, which contains several methods:

           

          Via javadoc tool, it's will be look like this.

          If we will see a html structure of this file, you could see a blockList - element. Do you not want to add a new blockList with your additions? It's should be UML, or something else...

           

          Or you need to do this only in source files?

          1 person found this helpful
          • 2. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
            KonTiki

            Thanks for reply, SkyTrace.

             

            I would like to keep this information OUT of the source files. The only comments that I want in the source files are short comments, usually alongside the code statements.

            You say that I can use some extensions of the Javadoc tool that will enable me to add diagrams and math equations.

            If so, great ! This is maybe all that I need.

            I didn't know that Javadoc had these capabilities.

             

            At present I use put this sort of information (except for the diagrams) into Javadoc header comments in front of each class, method, etc.

            The Javadoc headers for a class or for a method will collapse to a single line.

            But those for code blocks within a method will not. And that is where most of my large information sections are placed

            I really want to remove the non-code text from the source files so that reading through long classes is made easier . . .

            Is it possible to generate Javadoc files from .html files WITHIN the project package but OUTSIDE the source files ?

            • 3. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
              gimbal2

              Basically what you want to do is abuse javadoc to generate a wiki for you. That's not what the tool was built for, use a proper wiki solution to build up your external documentation. Javadoc is for generation API documentation.

              • 4. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                rp0428

                I think what is really needed here is a separate file type that can accommodate equation writing, UML diagrams, circuit diagrams, schematics, etc and which the person examining the code can open on a separate window on their large monitor when they needs to find the computation method used in a project.

                Huh? There are already file types for ALL of those things and software that uses them.

                Sure, the odd small comment will still be needed within the code but these would now be simply reference points between the code and the info file once the latter has been read and digested.

                That is pretty much the definition of a URL - Universal Resource Locator

                http://en.wikipedia.org/wiki/Uniform_resource_locator

                A uniform resource locator, abbreviated as URL (also known as web address, particularly when used with HTTP), is a specific character string that constitutes a reference to a resource.

                You can just use URLs to what you want to reference.

                Does anyone else know of any existing file structure that would be incorporatable into projects for the purpose I've described ?

                You can add just about any file you want into the projects for most software. Did you try this?

                And preferably compatible with the needs of all the major coding languages (i.e. Java, C/C++/C#/Obj C, Ada, Ruby) and their common IDEs.

                Why does an independent file need to be compatible with a coding language, the file isn't being embedded or read by the language?

                 

                I've tried searching under "code info(rmation) file" to no avail on Google.

                You likely used a URL when you did that.

                 

                And in JDeveloper the sample CodeInteraction extension allows you to just put the text 'code info(mation) file' into any file you want and highlight it. Then if you right click you can select a menu item that would do that 'Google search' for you.

                http://www.oracle.com/technetwork/developer-tools/jdev/samples-083838.html

                CodeInteraction - Shows how to get text from the code editor. Launches a google search on the currently selected text.

                Download and install JDeveloper

                Download and install the ESDK extension toolkit

                Build and deploy the CodeInteraction sample project

                Highlight and 'google search' any text you want

                 

                You can easily modify that sample code to access files on your own machine and launch the appropriate executable.

                 

                And, before you ask, yes - they have already invented a round object that can roll on a smooth surface - see the Wiki:

                http://en.wikipedia.org/wiki/Wheel

                1 person found this helpful
                • 5. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                  KonTiki

                  Huh? There are already file types for ALL of those things and software that uses them.


                  You mean a .html file, I suppose.

                   

                  You can just use URLs to what you want to reference.

                   

                  I didn't have URL links in mind, just brief reminders beside the code.

                  But links are an idea.

                   

                  You can add just about any file you want into the projects for most software. Did you try this?
                  Why does an independent file need to be compatible with a coding language, the file isn't being embedded or read by the language?

                   

                  No.

                  Because some IDEs - and some languages - do not permit just any old file type with any old rubbish in the project folder.

                  With these, everything present must have a purpose so that it may be used or (for info) ignored during building.

                   

                  And in JDeveloper the sample CodeInteraction extension allows you to just put the text 'code info(mation) file' into any file you want and highlight it. Then if you right click you can select a menu item that would do that 'Google search' for you.

                  Download and install JDeveloper

                  Download and install the ESDK extension toolkit

                  Build and deploy the CodeInteraction sample project

                  Highlight and 'google search' any text you want

                   

                  You can easily modify that sample code to access files on your own machine and launch the appropriate executable.


                  Interesting.

                  Am doing it right now..

                  I see it has code metrics, something Eclipse hasn't and trying to configure SonarQube plugin was breaking my heart.

                  Making LOC estimation simpler was one motive for moving all the info on classes, methods and switch options to a separate file  . . .

                   

                  And, before you ask, yes - they have already invented a round object that can roll on a smooth surface - see the Wiki:

                   

                  You're a guru, I suppose.

                  Whereas I'm just an engineer/scientist trying to make some cash from mobile apps.

                  Sorry if you're not tested enough by my thread.

                  Maybe you'll find more demanding posts on the higher-level Oracle forums.

                  • 6. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                    rp0428
                    You mean a .html file, I suppose.

                    No - I mean things like *.doc (Word document), *.pdf (Adobe file), *.vsd (Visio drawing file)

                     

                    You can embed text that includes a doc name and, using an extension like the sample I mentioned, open that file by launching the needed application and passing it the file name.

                    I'm just an engineer/scientist trying to make some cash from mobile apps

                    If you feel there is a lot of need for that create an extension and sell it. Oracle will list it on their third-party extensions web page.

                     

                    A new 'file type' would require a new 'application' of some sort to read that file type. I don't see why a new type of file is needed at all - there are already file types for almost any type of content you would want to use.

                     

                    All I see is that you want 'some way' to link to an external file stored 'somewhere' that has content of your choosing. That is what URLs, URNs and the rest of the 'URxxx' family was designed for.

                    1 person found this helpful
                    • 7. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                      KonTiki

                      I don't know if it's going to be easy to get third party tools to insert electric circuit diagrams, UML diagrams, general schematic diagrams, etc within .doc files. Equation formatting is possible (I recall doing it 20 years ago) in Word but I don't think it's any easier than in .html.

                      Using PDF . . . that means having Acrobat Writer, surely. Expense . . .

                      Don't know about .vsd.

                       

                      When I sort this out, it may well be no more than what you suggest - i.e. choosing from among existing tools and applying them according to my preferences in the organizing of a project.

                      I was thinking that an old .xhtml file would be best, as it's both .xml (organized data storage) and .html (agreeable display).

                      Most common languages' IDEs have good .xml handling tools.

                       

                      That's one helluva Java studio, JDeveloper. Thanks for that. Surprised it's free -- but glad it ain't.

                       

                      Happy weekend.

                      • 8. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                        jschellSomeoneStoleMyAlias

                        Rather certain that javadocs already supports links (thus images.)  I wouldn't be surprised if straight html doesn't work.  But the reference for @see provides a specific form that allow a link

                        1 person found this helpful
                        • 9. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                          jschellSomeoneStoleMyAlias

                          Comments and documentation are kept in source code because that is the best case scenario where both are kept up to date.  The problem isn't with options for documentation but rather that documentation isn't done at all.

                          1 person found this helpful
                          • 10. Re: CodeInfo File Type - An Alternative To Lengthy Comments Within Code . . .
                            KonTiki

                            Comments and documentation are kept in source code because that is the best case scenario where both are kept up to date.  The problem isn't with options for documentation but rather that documentation isn't done at all.


                            You must have a very large monitor, Jschell.

                            I don't.

                            Neither has my software engineer.

                             

                            Sometimes a person working in another organization (e.g. the company making the compiler & other software tools) might ask for the source code of an app, especially if it concerns an activity that they had no previous involvement with.

                            They'd have no expertise or interest in the (normally math or engineering) analytical aspects of the program, just in its implementation and my use (or misuse!) of language constructs in the code of the application.

                            To that extent, having as much lines of code as possible on their screen would be a great convenience.

                            It's also one thing trusting them with the source; another thing entirely trusting them with hard-earned insights or explanations of time saving approximations.

                             

                            I'll check out @see.

                             

                            Thanks.