Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
The structure of a FiM++ program requires that it end with the closing of a letter and the code author's name in a specific manner.
Dear Princess Celestia and Stack Exchange and String: A Sample:
...
Your faithful student, Southpaw Hare!
According to the language specification, the keyword "Your faithful student," (including the comma but not the following space) is used as an end tag for class definitions, and the following name is a comment with no syntactical effect.
The fact that the author is automatically included (if not strictly required) in every file makes me wonder if it can be used as a form of interpretable documentation akin to Java Docs. In other words, that other programs or editors would be able to parse out this name and use it in some manner.
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use "Your faithful students," for a plural form (or possibly "Yours faithful," or "Yours truly," for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
If creating a Java Docs methodology was considered, then what other features should be included? For one, a date seems common. Including some form of date comment at the top of the letter would probably look natural and not defy the design paradigm.
Since the language is new, unfamiliar to most, and honestly quite silly, here are a few resources to consider:
Original Release Announcement
October Followup
Sorry no one's given this any concern before me!
I'm heading development of the language, so I think I have a good grasp on the answer, here.
What is the requirement of such internal comment-based
documentation? Is there anything in this particular type
of syntax that would cause problems?
I've never considered an auto documentation technique like Javadoc, so there is no formal syntax for that. The compiler I'm working on completely discards comments, so it won't support it, but I'm sure it wouldn't be terribly hard.
Is the keyword sufficient to fit with the theme? It occurs to me
that the lack of ability to use "Your faithful students," for a
plural form (or possibly "Yours faithful," or "Yours truly," for an
ambiguous version) would make listing multiple authors look awkward
and unnatural (and looking like a natural pony-written letter is one
of the core design paradigms).
The idea of the author name on the last line was intended for the foremost author of the report, so multiple authors was never suggested before now. However, Your faithful students, would work nicely!
If creating a Java Docs methodology was considered, then what other
features should be included? For one, a date seems common. Including
some form of date comment at the top of the letter would probably
look natural and not defy the design paradigm.
Indeed! Perhaps something at the bottom of the report, like
(Written 2013-04-11)
Hope this help you. You have some great ideas, here, too! You should join the team!
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
An absolute pet hate are naming rules for the sake of it, when development enviroments are so good at letting users know what each item is.
As the title suggests are there any pitfalls if a developer were to name all types, objects, variables etc.. 'all in "snake_case", specifically in Kotlin. Ignoring the auto generated names for binding etc.
Coding style, such as naming, doesn't matter to the compiler.
But it matters to humans — and as a couple of wise people once said, “programs must be written for people to read, and only incidentally for machines to execute.” (They were probably exaggerating for effect, but I think there's still a grain of truth there.)
Consistency in naming means that you don't have to stop and think about whether to use underscores or capitals (or spaces or dashes or whatever inside backquotes); it makes classes and methods easier to find in your code as well as in libraries and frameworks; it plays better with Kotlin properties (which look for getXxx/setXxx/isXxx method in the bytecode); it removes a source of disagreement among developers; it's less likely to cause problems with IDEs and frameworks and source-code tools which tend to assume you're using standard naming conventions; it makes the codebase easier for new developers to get up to speed with.
But, more than all those, code which doesn't follow conventions iS_нa℞𝐝𝑒𝕽-τଠ𐍂ɘⱭ𐐼. When things that work the same look the same, differences are easier to see. The less time you spend deciphering names, that more time is left for understanding what the code is doing with them. It's the same reason why we use consistent indentation and spacing and structure and design patterns. With fewer surface differences, you can more easily see the underlying structures and patterns in the code, and deviations (and hence bugs) become more obvious.
Coding — by which I include debugging, maintaining, and enhancing as well as writing fresh code — is hard, and we humans are limited, so we should make things as easy for ourselves as possible. Developing software is a constant battle against complexity; every little simplification helps. You may think that using snake_case instead of camelCase is insignificant; but the mere fact you're asking about it here shows that it makes a difference!
The answers to this question and this question give many more (and better-argued) reasons why consistency is important.
(As it happens, I've spent many years using languages which prefer snake_case, and also with those which prefer camelCase, and I definitely find the latter easier to read in context. But that's a much less important consideration than consistency.)
Apart from arguing about that with other developers, and calls to all library functions looking different, the language will work perfectly and not care about that.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I know this question has been asked in various forms over and over again but I cannot find a single complete answer and I believe it is a general problem in the RDBMS/data area and industry. To explain the problem I will tell you a short (and maybe boring) story!
The Story
"I have a friend" who works in A company that uses 100+ systems. The scale and size of these systems vary from full-blown ITIL to custom/in-house, single purpose, LAMP/SQLite/CSV-based solutions. The vast majority of these systems, at one point or another use a database/data-store... Big-data has now become a trend, and A company though it is a very good idea to keep (or log) historical data from all systems forever! For that reason they have built a "warehouse". My friend is responsible for writing software that will do the analysis on some of this data ... however, he is kinda confused. There are thousands of tables in that warehouse containing data from the beginning of time (1970s I think :)).
The Problem
[Since I started telling you about this guy, I should probably continue]
My friend is very upset because of the lack of documentation in that warehouse. It seems that no-one knows what is what?! Few of the problems he faces (and I quote):
Man, some fields are constants... they have a special meaning to the application but I have no way of knowing? But that is OK... cause some other fields are bit-masks! Different bit values in the field have different meaning!
and he continues...
That's not all... these are the easy cases you know... Since we have data from multiple systems, we end up with a situation where different systems refer to the same thing in a different way... how can I explain it to you... for example, a network device has an FQDN, however some systems treat it as the primary key, some others don't and instead they allocate an auto-increment integer value, which in turn they use for foreign keys (you know... referencing this device).
and he can go on forever!
The Question
[Yes, it is one question]
He says:
We have come a long way regarding documentation in the software world... we have started with documents, moved to wikis and concluded to inline docblocks serving both as parameter/signature documentation and as wiki! We can auto-generate documentation, clear enough that a person in the other hemisphere and side of this world can easily follow!
and he continues:
... in the data side of things, we also had major achievements! Storage methods, serialization, transmission and data analysis techniques have evolved tremendously... We have also managed to map database tables into objects and in some cases we can even represent relationships!
So why the frell don't we have a standard method/technique of documenting our data structures in an RDBMS?
... he concluded :)
Enough with my friend, so my comments:
I know about comments on fields in various systems, but that is usually enough for a "deprecated" and not for an explanation
Updating a wiki or even worse a document, every time you release a database patch is not a solution... that patch should contain the relevant documentation!
ER diagrams can be easily generated based on the schema information, however this is not the easiest form of documentation to read... for anything more than 10 tables!
There is the saying (please comment if you know who said this! - respect)
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing
Why SQL doesn't provide the means to any?
Any kind of documentation would get stalled if not maintained.
Also, the SQL world provides all kind possibilities to document things:
comments in SQL files
comments in columns/tables metadata
as you said - E/R diagrams
the classic way of documenting stuff - docs and wikis
good discipline in adhering to an intuitive naming scheme for the things in DB - I think this should be the standard
We have all the tools we need, we just have to convince our managers to let us write the docs (lol)
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
This question does not appear to be about programming within the scope defined in the help center.
Closed 8 years ago.
Improve this question
I am writing a user manual and I have come to a discussion with a colleague. He says I cannot use the word "you" anywhere in the manual. Now I remember something about this at school but that was not for writing procedures. Also, doing some googling I observed that most tutorials where using it a lot. I would prefer using it but only if this is considered good practice. what do you think?
The alternatives that I know of are:
'You' (second person singular) - "You should put the plate on the table."
Imperative - "Put the plate on the table."
'We' (first person plural) - "We should put the plate on the table."
'The user' (third person singular) - "The user should put the plate on the table."
Passive - "The plate should be put on the table."
My own preferences are:
I prefer the imperative as the default mode, because it's the briefest (least verbiage).
I avoid the passive, and the first person plural.
I use the second person pronoun ("you") or a third person noun (e.g. "your system administrator") when I want an explicit subject instead of the imperative.
Some people believe that manuals should be written as if they were scientific papers. Others believe that technical accuracy and readability is more important. I'm of the latter persuasion - use "you" if it fits with your overall style, but be consistent in your usage - I find documents that switches between "you" and "we" are irritating (and it's a sin I've been guilty of myself).
Which is easier to understand?
Click the button. You will see a dialog box where you can type your name.
or
The action of clicking the button will cause the appearance of a dialog box allowing the possibility for the user to enter his or her name.
The first is much easier to grasp. (Using "you" can sometimes be sloppy, but that tends to be in cases where it's used as a substitute for "one", or "some people", or "people in general". It's fine to use it where you are actually referring to the person reading the text.)
If you want, you can avoid the
you-style by writing in the
passive/imperative style. You can
also try the 'we' approach, but that
might sound a bit childish. You're
doing nothing wrong with using you
though.
To avoid writing in the you-style,
use the passive/imperative style. The
we-approach might also work, though
it might sound a bit childish. There
is nothing wrong with using you
though.
We can avoid writing in the you-style
by employing the passive/imperative
style. Or we could use the
we-approach, though we might sound a
bit childish. One could try the one
approach, but risk sounding to
stiff-upper-lip and alienating the
reader. We don't mind using you once
in a while, though.
I myself do prefer the second line. A series of commands is easier to follow then a story in the you-form.
You should be writing explantions in the third person.
The Java streams model is a classic Decorator pattern example.
You should write instructions in the second person, but even then, it's still not a good idea to refer to the reader as "you".
Create a constructor that can initialize lists based on a given list of lists.
Now, how did you feel after I issued 2 commands to you, my reader?
Technical Writing Enforce the rule of using passive text only. which mean avoiding "you" will be a good idea to stay in the safe side. that's based on how i do it personally.
I would do what Google, Microsoft, Yahoo, etc do. Here's a random Help page from Google:
http://mail.google.com/support/bin/answer.py?hl=en&answer=8494
shows that "you" is being used. You can check how Microsoft writes their User Manual too.
As a side note, I wouldn't use "I" or "we".
I think if you are providing imperatives, such as "Open the door", or otherwise directly addressing the reader, then you should use "you" instead of making yourself more difficult to comprehend by talking about some abstract user.
Even in scientific papers, some of the most formal writing I can think of, it is debatable whether or not I, we and other first person language is permissible. As much as high school grammar teachers might like you to think otherwise, there is no universally appropriate scheme.
I would say just be careful. It could come across as too casual. If the intended audience is business-y, I would avoid it. However, if it's a home user scenario or the marketing is casual (think Southwest Airlines), I'd say go with it.
Just don't overuse. Then it becomes taxing on the reader.
Sample of how it's intended to be used?
It all depends on the tone and style of your writing. Formal approaches discourage the use of "you". Personally, I like
to use a style that is concise, to the point and relatively informal. I have no problem with the "you" word when used sparingly.
Avoid over usage as in:
When you want to start the application you have to enter your password and then you have to select the function you want to use.
From the Handbook of Technical Writing. 8th Edition (p. 262):
You can make sentences shorter by leaving out some articles(a, an, the), some pronouns (you, this, these), and some verbs, but such sentences may result in telegraphics style and be harder to understand.
So, I'd say it's OK to use you, but like Gilbert Le Blanc said in his comment, it's often better to write 'then click the button' instead of 'then you click the button'.
Impersonal form should be preferred. The use of 'you' would be too clear, and most of your clients will believe you are not professional. A clear manual will also reduce the need for post-sale customer support, and cause losses to the company.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I have noticed I do not code as much as I use to. Today I dedicate more time to analysis and design, then I communicate that design to programmers. Then they do the coding. This has affected my coding productivity, because I must consult references and rely on intellisense. Things are becoming more complex everyday
Now, here is the irony. If I were to hire a programmer and ask him/her to sit in front of a computer, I may ask to do some coding and I would check abilities. I would evaluate them based on their use of memory vs. consulting references. Maybe I will prefer that programmer who did not consult too much, but who knows what they are doing.
What is your opinion and experience?
I would say that a developer who knows how to find the answers is better than one who has an overall good knowledge already. I find that intellisense is a good tool for finding answers, besides it is too much to remember all method names, arguments, overloads, etc.
I use memory to get me into the right general area (e.g. knowing which classes to use or at least which namespace they'll be in) and then often Intellisense/MSDN for the exact method name or arguments to use.
Having said that, Stack Overflow is improving my ability to code without any references (or even compilation) - I'm sure code will just work out of the box for me more often now than it used to. (I tend to post and then check the code works, add links to MSDN etc - assuming I'm reasonably confident in the approach.)
Someone knowing what resources are available, and how to find the answers, and how to effectively debug - these are qualities I look for now in prospective employees.
I used to consult my memory only, but two things have happened:
Class libraries have gotten larger, so has the number of languages available
The ratio of programming-related memory to personal-life-related memory has shifted away from code
Programming today is also eight times harder than it was when I started. I used to work on 8-bit machines, now I'm working on 64-bit ones. :)
I once was at a job interviewed with the CTO of a company. He asked a question based on a real life problem the company had a while back and solved. It was a multi step problem.
I was standing in front of a whiteboard working through my solution and struggling through a particular part, a part I would use google for before even attempting it, had I been tasked with solving this problem for real instead of for an interview. He asked me at that point, "would you do anything different if this wasn't an interview question." I responded, "Yes. I would exhaust all possibilities of using a third party component for this part of the task and look up the solution, because it is a well defined problem thats been solved several times." There was a bit more discussion where I justified my answer, explained exactly what I would research, and I solved some other parts of the question. In the end I was offered and accepted the job, partly because of knowing how to find out what I didn't know.
Being able to use references is as important as being able to code from memory. Obviously, if you are a one language shop, and want people proficient in that language,the person should be able to write a complete hello world app in notepad. Interview problems should focus on small problems, and one should not worry about small syntax errors. This is why a whiteboard is the best IDE for interview questions.
Unless you demand all your coders use notepad and don't give them internet access, don't be as concerned by the syntax. If you do sit them down in front of a computer, worry about the finished product as well as the technique used to get there.
I'm a PHP programmer in my early 30's. I rely on PHP's excellent documentation, for several reasons:
Programming concepts don't change. If I know what my object models are and how I want to manipulate data, then there's dozens of ways to implement the details. The details are important, but a better grasp of the design and structure is more important
PHP has notoriously inconsistent functions. One string function might use ($needle,$haystack) as parameters, and another might use ($haystack,$needle). Trying to keep them straight isn't worth the hassle when you can just type php.net/function_name and get the reference.
I don't rely on intellisense, simply because I haven't found a decent IDE for PHP that does it well. Eclipse is ok, but it's not fantastic. Netbeans gives me 'PHPDoc not found' for all the built-in PHP functions whenever I install it. There's nothing that I've found so far that beats out the documentation.
The bottom line is that the ability to memorize functions isn't indicative of coding ability. Obviously there's a key set of basic functions that a good programmer will know just from extensive usage over time, but I wouldn't base a hiring decision on whether someone knows substr_replace vs. str_replace from memory.
Because I've read either the documentation, or articles, or a book on a subject, the things I learn on a topic are organized. The result is that, if I can't bring something up from memory, I can probably find it quickly through IntelliSense or the Object Browser.
Worse come to worst, I can pick up the book again; something these youngsters are not being taught to do.
John Saunders
Age 51
Pretty much Google + Old Projects + my memory (of course)
References will not solve your problems though, its only for the nuts and bolts, the higher level of problem solving is the actual "programming" part IMHO.
I tend to use Intellisense and Resharper much more than I used to before, but this has helped my overall productivity. If I can get the idea of how I want to solve something and then use tools to get the more boring parts like class names and function signatures, why shouldn't I use the tools I have? I feel relieved that Jon Skeet has a similar approach it seems.
I rely on my bookmarks and books... and my ability to use them effectively. I have multiple books above my desk, including a copy of the ISO C90 standard. Moreover, I use Xmarks to have access to my bookmarks wherever I go. Sometimes, I make a pdf out of a particular page and upload it to my web-site if it is important enough.
Sometimes the information provided by the resources I use makes its way into my terrible memory... maybe.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.