I need to use HTML comments to store specific data, but I don't want use comment schemes that already exist, as generated by programs like Dreamweaver <!-- #BeginLibraryItem "/File.lbi" --> or Frontpage.
How do I know what comment scheme would be least problematic, or at least not look like other existing comment conventions?
PS: I'm told a double hypen "--" in comments sometimes breaks rendering.
You need at least <!-- --> to have a comment, and yes, you should avoid having "--" in the middle of the comment; the "--" are the actual comment delimiters. Other than that, you can just prefix it with any string and I think you'll be good -- e.g., <!--JEREMY_RUDD: -->.
However, storing data in comments sounds like a suboptimal idea. Can you elaborate on this? Have you considered whether, say, something like JSON might not be more appropriate?
I've started a standard, inspired by JSDoc and Javadoc: HTMLDoc.
Related
I'm not sure this is the right place to ask this. I would like to know how best to style parts of messages from l10n properties files. For example, my client want this message and formatting in a help window:
This is a self-assessment and comparison application.
Simplest solution would be to include the HTML tags in the messages.properties entry for this label. The problem with that is that the 40 translators that will process the messages.properties are bound to make mistakes like deleting the <, translating the attributes or styles of the HTML markup etc. Also it makes maintaining the markup and styling difficult for the devs.
Any better way to do this?
The solution I've seen typically done just uses th:utext with HTML tags in the .properties files. I would opine it does create a maintenance hassle as you mention and should be kept to a minimum.
One workaround is to create separate strings in some cases, like:
<span th:text=#{thisIsA}>This is a </span><strong><span th:text="#{selfAssessment}">self-assessment</span></strong>
However, this is error-prone since certain languages may change the order of the words. So that's not a great option.
If the HTML tags specifically are an issue, another way albeit somewhat ugly could be:
thisIsASelfAssessment=This is a {0}self-assessment{1}.
Or even
thisIsA=This is a {0}.
selfAssessment=self-assessment
But that might be confusing for the next developer reading it and may introduce the same issue you have with the 40 translators looking at it since you have curly braces. It also all becomes very tedious and generates more lines.
So in the end, you're likely best going with the simplest solution of utext.
Project-wise, you could have the initial translation done without the markup and add the markup in after they are done with a first pass at translating it. The issue may arise in the future when you need to change strings, but doing this would minimize some headache. It could make sense to keep these strings in a separate block in the .properties file so you can target them later.
Good question as I've had this issue myself.
I just stumbled across this gem in our code:
my $str_rep="lower(replace(replace(replace(replace(replace(replace(replace(replace(replace(replace(replace(replace(replace(field,'-',''),'',''),'.',''),'_',''),'+',''),',',''),':',''),';',''),'/',''),'|',''),'\',''),'*',''),'~','')) like lower('%var%')";
I'm not really an expert in DB, but I have a hunch it can be rewritten in a more sane manner. Can it?
It depends on the DBMS you are using. I'll post some examples (feel free to edit this answer to add more).
MySQL
There is really not much to do; the only way to replace all the characters is nesting REPLACE functions as it has already been done in your code.
Oracle DB
Your clause can be rewritten by using the TRANSLATE function.
SQL Server
Like in MySQL there aren't any functions similar to Oracle's TRANSLATE. I have found some (much longer) alternatives in the answers to this question. In general, however, queries become very long. I don't see any real advantages of doing so, besides having a more structured query that can be easily extended.
Firebird
As suggested by Mark Rotteveel, you can use SIMILAR TO to rewrite the entire clause.
If you are allowed to build your query string via Perl you can also use a for loop against an array containing all the special characters.
EDIT: Sorry I did not see you indicated the DB in the tags. Consider only the last part of my answer.
Your flagged this as Perl, but it's probably not?
Here is a Perl solution anyway:
$var =~ s/[\-\.\_\+\,\:\;\/\|\\\*\~]+//g;
Sorry I don't know the languages concerned, but a couple of things come to mind.
Firstly you could look for a replace text function that does more that just a single character. Many languages have them. Some also do regular expression based find and replace.
Secondly the code looks like it is attempting to strip a specific list of characters. This list may not include all that is necessary which means a relatively high (pain in the butt) maintenance problem. A simpler solution might be to invert the problem and ask what characters do you want to keep? Inverting like this sometimes yields a simpler solution.
In short, this is bad web development and UX:
But solving it by using CSS3 word breaking (code & demo) can lead to an 'awkward whitespace' situation, and strange cut-offs — here's an example of both:
Maybe it's not such a big deal, and the UX perspective of it is here, but let's look at the semantics of one of the solutions:
You could ... use the <wbr> element to indicate an optional word
break opportunity. This will tell the browser to insert a line break
as necessary to flow onto a new line inside the container.
The first question: is using <wbr> semantic HTML? (Does it at least degrade gracefully?)
In either case, it seems that being un-semantic in the general sense is a small price to pay for good UX functionality.
However, the second quesiton is about the big picture:
Are there any schema.org (microdata/RFDa) ramifications to consider when using <wbr> to split up an email address? Will it still be valid there?
The wbr element is defined in the HTML5 spec. So it's fine to use it. If it's used right (= according to the definition in the spec), you may call it also "semantic use".
I don't think that there would be any problems in combination with micordata/RDFa. Usually you'd provide the URL in an attribute anyway, which can't contain wbr elements of course: foo<wbr>#example<wbr>.com.
For element content I'd guess (didn't check though) that microdata/RDFa parsers should use the text content without markup resp. understand what is markup and what is text, otherwise e.g. a FOAF name would be <abbr>Dr.</abbr> Foo instead of Dr. Foo.
So you can bet that microdata/RDFa parsers know HTML ;), and therefor it shouldn't be a problem to use its elements.
PostgreSQL has allowed me to name a column "campaign_$". I like the name because it's short and to the point, and other potential names like "campaign_receipts" seem longer and less clear.
BUT, I wonder if I'll eventually regret putting a $ symbol in a column name, either in PHP or in some other distant part of the architecture. Should I just stick to letters and underscores?
Thanks!
Yes, you should. "campaign_receipts" is a better name.
You probably won't regret, but I still wouldn't recommend it.
What happens when you expand into Europe?
Also, it will look strange and confusing to new developers.
In addition to the other excellent reasons I'll also mention that "$" in my mind is not clear at all. Does that mean campaign expenses? Campaign savings? Campaign values?
There's a VERY strong convention that tables and columns are named using only letters, numbers, and (possibly) underscores, so I would consider this poor style. Beyond the i18n concerns that other posters mention, there are probably a very large number of tools that expect table and column names following this convention.
I think it is bad practice to put special characters into a column name. Just spell out the word like campaign_money or campaign_funds and then the issue of internationalization or other possible issues become a thing of the past.
It should be fine, however it may cause you more problems down the line when you want to export the data to another system, things like that.
It's good to get into the habbit of naming columns/variables etc with no special characters, as usually they are more trouble than they are worth.
I wouldn't use it.
The "$" might not be valid in future databases you use (at some point you might migrate away from PostgreSQL to something else) and it also might pose problems at the application level if you do anything that maps column names to object properties if your programming language doesn't allow method names to have "$" in them.
Just my suggestion.
I've always hated comments that fill half the screen with asterisks just to tell you that the function returns a string, I never read those comments.
However, I do read comments that describe why something is done and how it's done (usually the single line comments in the code); those come in really handy when trying to understand someone else's code.
But when it comes to writing comments, I don't write that, rather, I use comments only when writing algorithms in programming contests, I'd think of how the algorithm will do what it does then I'd write each one in a comment, then write the code that corresponds to that comment.
An example would be:
//loop though all the names from n to j - 1
Other than that I can't imagine why anyone would waste valuable time writing comments when he could be writing code.
Am I right or wrong? Am I missing something? What other good use cases of comments am I not aware of?
Comments should express why you are doing something not what you are doing
It's an old adage, but a good metric to use is:
Comment why you're doing something, not how you're doing it.
Saying "loop through all the names from n to j-1" should be immediately clear to even a novice programmer from the code alone. Giving the reason why you're doing that can help with readability.
If you use something like Doxygen, you can fully document your return types, arguments, etc. and generate a nice "source code manual." I often do this for clients so that the team that inherits my code isn't entirely lost (or forced to review every header).
Documentation blocks are often overdone, especially is strongly typed languages. It makes a lot more sense to be verbose with something like Python or PHP than C++ or Java. That said, it's still nice to do for methods & members that aren't self explanatory (not named update, for instance).
I've been saved many hours of thinking, simply by commenting what I'd want to tell myself if I were reading my code for the first time. More narrative and less observation. Comments should not only help others, but yourself as well... especially if you haven't touched it in five years. I have some ten year old Perl that I wrote and I still don't know what it does anymore.
Something very dirty, that I've done in PHP & Python, is use reflection to retrieve comment blocks and label elements in the user interface. It's a use case, albeit nasty.
If using a bug tracker, I'll also drop the bug ID near my changes, so that I have a reference back to the tracker. This is in addition to a brief description of the change (inline change logs).
I also violate the "only comment why not what" rule when I'm doing something that my colleagues rarely see... or when subtlety is important. For instance:
for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse
I use comments in the following situations:
High-level API documentation comments, i.e. what is this class or function for?
Commenting the "why".
A short, high-level summary of what a much longer block of code does. The key word here is summary. If someone wants more detail, the code should be clear enough that they can get it from the code. The point here is to make it easy for someone browsing the code to figure out where some piece of logic is without having to wade through the details of how it's performed. Ideally these cases should be factored out into separate functions instead, but sometimes it's just not do-able because the function would have 15 parameters and/or not be nameable.
Pointing out subtleties that are visible from reading the code if you're really paying attention, but don't stand out as much as they should given their importance.
When I have a good reason why I need to do something in a hackish way (performance, etc.) and can't write the code more clearly instead of using a comment.
Comment everything that you think is not straightforward and you won't be able to understand the next time you see your code.
It's not a bad idea to record what you think your code should be achieving (especially if the code is non-intuitive, if you want to keep comments down to a minimum) so that someone reading it a later date, has an easier time when debugging/bugfixing. Although one of the most frustrating things to encounter in reading someone else's code is cases where the code has been updated, but not the comments....
I've always hated comments that fill half the screen with asterisks just to tell you that the function returns a string, I never read those comments.
Some comments in that vein, not usually with formatting that extreme, actually exist to help tools like JavaDoc and Doxygen generate documentation for your code. This, I think, is a good form of comment, because it has both a human- and machine-readable format for documentation (so the machine can translate it to other, more useful formats like HTML), puts the documentation close to the code that it documents (so that if the code changes, the documentation is more likely to be updated to reflect these changes), and generally gives a good (and immediate) explanation to someone new to a large codebase of why a particular function exists.
Otherwise, I agree with everything else that's been stated. Comment why, and only comment when it's not obvious. Other than Doxygen comments, my code generally has very few comments.
Another type of comment that is generally useless is:
// Commented out by Lumpy Cheetosian on 1/17/2009
...uh, OK, the source control system would have told me that. What it won't tell me is WHY Lumpy commented out this seemingly necessary piece of code. Since Lumpy is located in Elbonia, I won't be able to find out until Monday when they all return from the Snerkrumph holiday festival.
Consider your audience, and keep the noise level down. If your comments include too much irrelevant crap, developers will just ignore them in practice.
BTW: Javadoc (or Doxygen, or equiv.) is a Good Thing(tm), IMHO.
I also use comments to document where a specific requirement came from. That way the developer later can look at the requirement that caused the code to be like it was and, if the new requirement conflicts with the other requirment get that resolved before breaking an existing process. Where I work requirments can often come from different groups of people who may not be aware of other requirements then system must meet. We also get frequently asked why we are doing a certain thing a certain way for a particular client and it helps to be able to research to know what requests in our tracking system caused the code to be the way it is. This can also be done on saving the code in the source contol system, but I consider those notes to be comments as well.
Reminds me of
Real programmers don't write documentation
I wrote this comment a while ago, and it's saved me hours since:
// NOTE: the close-bracket above is NOT the class Items.
// There are multiple classes in this file.
// I've already wasted lots of time wondering,
// "why does this new method I added at the end of the class not exist?".