Good strategies for developing code for browsers?

Question

I often write throwaway code (in a research environment ) - for example, to study an algorithm or model for a scientific property or process. Many of these "experiments" are one-time, but sometimes I find that I need to use a little later. For example, I just dug up the code for matching strings that I wrote 7 years ago (stopped due to other priorities), but which is now valuable for a colleague's project. Looking at it (did I really write such an impenetrable code?), I understand that I could do something to help me when I restarted the “project” (“experiment” is still the best word). An early experiment "worked", but I know that at that time I would not have time to refactor, since my priorities lie elsewhere.

What approaches are cost effective in allowing this work and reusing it?

EDIT : I answered my question (below) because there are problems that go beyond the actual source itself.

Answer 1

I do not agree with all the answers saying "write comments". This is suggested as a trick for the code itself, not understood.

Get a copy of Code Complete (Steve McConnell, 2nd Edition). If you learn how to write supportive code first, you won’t need more time and you can return to work later with less problems.

Which would you prefer:

• Cryptic code with comments
• Basically the code is OK without?

I strongly prefer the latter, since the OK code is easier to understand in situations where the secret code has been uncommented, and comments are another place that the original developer may make mistakes. The code may be wrong, but it is never wrong.

As soon as you feel comfortable with Code Complete, I would recommend The Pragmatic Programmer , as it provides some tips for developing software at a higher level.

Answer 2

[Answer to my own question] There are several more aspects of the problem that have not been raised, and which I would find useful in re-examining it. Some of them may be "self-evident", but remember that this code was previously SVN and IDE.

• Discoverability . It was actually hard to find the code. I find this in my SourceForge project, but there are so many versions and branches for 7 years that I cannot find them. Therefore, I would have to have a system that would look for the code, and until the IDE appears, I don't think it was.
• What is he doing? . The current check contains about 13 classes (all in one package, because at that time it was not easy to reorganize). Some of them are understandable ( DynamicAligner ), but others are opaque ( MainBox , named because it expanded Swing Box). There are four main() programs, and the distribution actually has about 3 subprojects. Therefore, it is imperative to have an external manifest about what the components really were.
• instructions for launching it . When the program starts, main() offer a brief use of the command line (for example, DynamicAligner file1 file2 ), but does not say what the contents of the files look like. I knew this at that time, of course, but not now. Thus, example files must be linked in sibling files. They are more valuable than trying to document file formats.
• Does it work? . It should be possible to run each example without thinking. The first question will be what are the relevant libraries, time intervals, etc. Still relevant and available. One former employee wrote a system that only works with a specific version of Python. The only answer is to rewrite. Therefore, of course, we must avoid any locks where possible, and I trained myself (although not necessarily employees) for this.

So how can colleagues and I avoid problems in the future? I believe that the first step is that when creating the code there must be a discipline to create a “project” (albeit a small one) and that these projects must be versioned. This may seem obvious to some of you, but in some environments (academic, domestic) there is significant overhead for creating a project management system. I suspect that most of the academic code is not under version control.

The question then becomes how projects should be organized. They cannot be on Sourceforge by default, because the code is (a) trivial and (b) does not open by default. We need a server on which there can be both utility projects and private ones. I would estimate that the setup and startup efforts are around 0.1 FTE - this is 20 days a year from all sides (installation, training, maintenance) - if there are simpler options that I would like to know, as this is a big expense in some cases - do I spend my time setting up a server or writing documents?

The project should try to encourage good discipline. This is really what I was hoping to get from this question. It may include:

• The template of the necessary components (manifest, README, commit log, examples, required libraries, etc. Not all projects can work under maven - for example, FORTRAN).
• A search tool for a large number (at least hundreds) of small projects for mnemonic strings (I liked the idea of ​​dumping code in Googledocs, and this may be a fruitful prospect, but this is an additional maintenance effort).
• Clear naming conventions. They are more valuable than comments. I now regularly have names like iterateOverAllXAndDoY. I am trying to use createX () rather than getX () when the program actually creates the information. I have a bad habit of calling a routine () process, not convertAllBToY ().

I know, but have not used GIT and Mercurial and GoogleCode. I do not know how much effort they must create and how many my problems they answer. I would be glad if there was an IDE plugin that helped create better code (for example, "poor choice of method name").

And no matter what approaches they should get, naturally, people who do not naturalize, have good code discipline and are worth the effort.

Answer 3

As the excellent answers show in your other post , and in my own experience between the software used for research and the software, there is a difficult gap between which was designed. In my opinion, Code Complete may help a little, but not much. As an economic question, is it worth reorganizing everything for reuse compared to a random reward for finding something later for yourself? Your balance point may vary.

Here's a practical tip for storing fragments. Instead of full comments, enter a few keywords:

• "graph isomorphism shell"
• "polymerized annealing"
• "string match feynmann"
• "equilibrium"

and then put the code somewhere on Google to search, for example, a GMail account.

Edit: I can add that free Google Sites are really searchable wikis that are a good place to put code as attachments or pastes.

In addition, I must say that I am a fan of Code Complete and have provided copies to literacy students who have been writing research software for several years. This is a good start, but not a silver bullet. Now I am writing an article on the use of open source frameworks for solving problems of scientific data management, and one of the conclusions is that some expert knowledge in the field of software development is necessary for long-term systems. Many research projects probably should have financed this from the very beginning.

Answer 4

I think the most important thing (if you do not have refactoring, this will not happen) is to comment and document your thought process at that time. This will help make the code less impenetrable and help you find good bits when necessary.

Answer 5

Comments Describe what you think and why you decided to implement something in a certain way, including what alternatives you have considered. There are probably all kinds of fancy solutions, but just commenting your code properly while you are writing seems to work best.

Answer 6

I would say that others said they commented on “why,” why the code was written and intended to be used, but I would also add this:

The code, as if you were planning on putting this into production, even when you were just messing around. Code for:

• Clarity and readability
• Follow the coding rules of the time. (naming conventions, etc.). Despite the fact that such agreements change over time, if you adhere to standards that you are likely to be able to understand later.
• Security (if applicable)
• performance (if applicable)

In particular, I would like to emphasize the first point, but others are also important. I find that if I use the “test code” later, I just use it if it works, rather than refactoring.

Answer 7

No no no no no!

Do not write an ejection code even in a research environment. You are welcome!

Currently, I was busy with such a catchy code, namely with a BLAST project. The fact is that it began as a playground, but then it became somewhat successful, now it is a neat tool with many concepts, but the code is practically uncontrollable. But that is not the point.

Most importantly, you conduct research for engineers to subsequently benefit from your results. Having done a good scientific work on the general concept and writing a tool that proves it successfully, you can easily forget that you are not doing this for publication, but only for PhD. You do this for the benefit of humanity. Your code may contain a bunch of "special cases" that are difficult to debug, a set of quirks and hacks that don't fit into any article in the conference. It is especially important to document and comment on such things in your code.

If a developer decided to implement his concepts in a commercial product, he could study the quirks and hacks from your code, and the implementation would have fewer errors than it could be. Everyone says: "Wow, his research on A is really useful!" But if you write "throwaway", they say that "his concept looks beautiful on paper, but X tried to implement it and drowned in a bunch of mistakes."

( EDIT : taken from the comments below). To help future developers of your code base, you do not need much. First, a comment on what each function does . Secondly, make sure that each non-obvious correction of a complex error is placed in a separate commit in the version control system (of course, with the corresponding comment). This is quite enough. And if you even make things modular (even if they are not ready for direct reuse), which is three times more expensive, according to Brooks), the engineers who conduct your research will adore you.

I think the world would be a better place if the researchers cast off their pride and stop arrogantly thinking that they are not these dirty coders who do the grim work of writing good code. Writing good code is not just a job for these stupid programmers. This is truly a valuable thing that everyone should strive for. Without this, your experimental site, your code, your brainchild will simply die.

Answer 8

I probably missed this whole discussion, I often do it, but here comes the invitation for brick clans and downvoting ...

If he throws the code, throw it away!

If you do not want to throw it away, follow the tips above. For me, and I write a lot of code, the question of whether it will be thrown away or transferred to a reusable state and saved against a rainy day comes down to economics.

Is it possible to foresee the circumstances in which this code will be useful again? Once in the blue moon, twice a year, every month?

Can I rewrite this code in less time than it takes to make it reusable? If the answer to this question is “No,” how many times will I have to reuse it to upgrade it now? (Back to the previous question.)

If I make this code reusable, can I find it again when I want? (Anyone has ever had the experience of knowing with absolute certainty that somewhere in your code repository there is only the fragment that you want, but without a clue about what it was called, and where to look and what to do, to grep?)

Finally, a three-step approach to writing code fast. Stop after what you need:

1) Document the code as a black box. Inputs, outputs, operations (s). Save this document.

2) Write instructions on how to create / interpret / install the code if you ever have to port it. Write these instructions carefully.

3) Only if it’s worth the effort, improve the quality of the source code so that the code is supported in the future. Make sure the sources are in the source control system and available.

Hi

Mark

Answer 9

Some strategies:

• Good comments. It is difficult to repeat what you cannot find or understand later.
• Keep every request backed up or under source control.
• You have a common library of useful functions that you “advertise” something to reuse it.

Answer 10

You could also borrow the idea of ​​unit tests from TDD developers (test takers). You need to make sure that throwaway code really works fine, so why not express the checkme link with a small unit test? This would have two advantages:

• Reading the test code speaks clearly enough about the intent of the release: after all, it expresses its expectations in one language: code.

• This will also help with the 4th self-care issue: "Still working?". Well, it's simple: just run unit tests, and they will tell you what and where (and with luck), why (it) doesn't work.