[Firebird-docs] Comments on Firebird 3 Developers's guide

[Mark R. <ma...@la...>]

Great it is now released!

Some comments on things I noticed when reading (Version 1.000, PDF 
physical page numbers, not print page numbers). I only read the 
introduction and the Java part (I'm biased ;):

Page 9: "About the Author" doesn't say much about the author, add a 
small biography?

Page 15: Note on use of identity column in Firebird 3 should mention 
that creating the sequence and trigger is not necessary if using a 
GENERATED BY DEFAULT AS IDENTITY clause

Page 15: Usage of BLOB SUB_TYPE 1 SEGMENT SIZE 80 is curious: a. 
SUB_TYPE 1, better would be SUB_TYPE TEXT (more readable/explicit), and 
b. as far as I'm aware SEGMENT SIZE has been deprecated, and doesn't 
even do anything except maybe for ESQL-usage, which isn't covered in 
this guide. I think it should be replaced with just BLOB SUB_TYPE TEXT 
to avoid promoting outdated practices.

Page 22: SP_ADD_INVOICE_LINE generates an id for invoice_line_id, but 
there is also a trigger that does this. Removing this would also remove 
the need for the grant usage to the stored procedure.

Page 27: Name of the zip (and the database) is rather generic, can we 
use a more specific name (eg devguide-example.fdb, and 
fb_devguide_db_3_0.zip)?

Page 204: How are we going to handle version updates of dependencies? 
For example Jaybird 3.0.0 has already been superseded with version 
3.0.3. And current latest jOOQ version is 3.10.5, latest Spring is 
5.0.4, (or 4.3.14 for 4.x), etc.

Just updating could break examples, but we may want to add a note that 
people should check if they need to use newer versions.

Page 206: It might be helpful to add the jetty-maven-plugin. This allows 
people to run the example project without having to deploy it (manually) 
to tomcat or another servlet engine.

Just add to the list of plugins:

             <plugin>
                 <groupId>org.eclipse.jetty</groupId>
                 <artifactId>jetty-maven-plugin</artifactId>
                 <version>9.4.8.v20171121</version>
             </plugin>

Then running the example application is just a matter of using

mvn jetty:run

from the commandline (or executing this goal from within your IDE), and 
opening http://localhost:8080/ in your browser.

Page 211: Add callout that people must update the directory-element in 
the jOOQ configuration in example.xml

I also believe it is possible for jOOQ to have this configuration in the 
pom.xml, this might make the code more self-contained.

Page 213: Odd comments in code with a lot of question marks, maybe 
originally Russian lost in conversion?

Page 231: Explicit use of a sequence, while the CUSTOMER table has a 
trigger to do this. Also, the current user may not have usage rights on 
the sequence.

Page 277: The fbjavaex.zip sources contain Russian comments and the 
webpage displayed by the project is a mix of Russian and English, it 
would be helpful if this is replaced with English.

The documentation contains sources and screenshots that do have English 
where the example project has Russian, so maybe the wrong example zip 
was published?

I haven't dug to deep in the actual source code, I might have some more 
comments on that later ;)

Mark
-- 
Mark Rotteveel