Index: trunk/src/org/openstreetmap/josm/gui/mappaint/styleelement/placement/OnLineStrategy.java
===================================================================
--- trunk/src/org/openstreetmap/josm/gui/mappaint/styleelement/placement/OnLineStrategy.java	(revision 11751)
+++ trunk/src/org/openstreetmap/josm/gui/mappaint/styleelement/placement/OnLineStrategy.java	(revision 11752)
@@ -49,5 +49,5 @@
     }
 
-    private double upsideTheta(HalfSegment best) {
+    private static double upsideTheta(HalfSegment best) {
         double theta = theta(best.start, best.end);
         if (theta < -Math.PI / 2) {
@@ -68,15 +68,24 @@
     public List<GlyphVector> generateGlyphVectors(MapViewPath path, Rectangle2D nb, List<GlyphVector> gvs,
             boolean isDoubleTranslationBug) {
+        // Find the position on the way the font should be placed.
+        // If none is found, use the middle of the way.
         double middleOffset = findOptimalWayPosition(nb, path).map(segment -> segment.offset)
                 .orElse(path.getLength() / 2);
 
+        // Check that segment of the way. Compute in which direction the text should be rendered.
+        // It is rendered in a way that ensures that at least 50% of the text are rotated with the right side up.
         UpsideComputingVisitor upside = new UpsideComputingVisitor(middleOffset - nb.getWidth() / 2,
                 middleOffset + nb.getWidth() / 2);
         path.visitLine(upside);
-
-        boolean doRotateText = upside.shouldMirrorText();
+        boolean doRotateText = upside.shouldRotateText();
+
+        // Compute the list of glyphs to draw, along with their offset on the current line.
         List<OffsetGlyph> offsetGlyphs = computeOffsetGlyphs(gvs,
                 middleOffset + (doRotateText ? 1 : -1) * nb.getWidth() / 2, doRotateText);
 
+        // Order the glyphs along the line to ensure that they are drawn corretly.
+        Collections.sort(offsetGlyphs, Comparator.comparing(e -> e.offset));
+
+        // Now translate all glyphs. This will modify the glyphs stored in gvs.
         path.visitLine(new GlyphRotatingVisitor(offsetGlyphs, isDoubleTranslationBug));
         return gvs;
@@ -100,9 +109,8 @@
             offset += (rotateText ? -1 : 1) + gv.getLogicalBounds().getBounds2D().getWidth();
         }
-        Collections.sort(offsetGlyphs, Comparator.comparing(e -> e.offset));
         return offsetGlyphs;
     }
 
-    private Optional<HalfSegment> findOptimalWayPosition(Rectangle2D rect, MapViewPath path) {
+    private static Optional<HalfSegment> findOptimalWayPosition(Rectangle2D rect, MapViewPath path) {
         // find half segments that are long enough to draw text on (don't draw text over the cross hair in the center of each segment)
         List<HalfSegment> longHalfSegment = new ArrayList<>();
@@ -192,6 +200,6 @@
         private final double endOffset;
 
-        private double upsideUpLines = 0;
-        private double upsideDownLines = 0;
+        private double upsideUpLines;
+        private double upsideDownLines;
 
         UpsideComputingVisitor(double startOffset, double endOffset) {
@@ -223,5 +231,9 @@
         }
 
-        public boolean shouldMirrorText() {
+        /**
+         * Check if the text should be rotated by 180°
+         * @return if the text should be rotated.
+         */
+        boolean shouldRotateText() {
             return upsideUpLines < upsideDownLines;
         }
@@ -236,4 +248,9 @@
         private OffsetGlyph next;
 
+        /**
+         * Create a new {@link GlyphRotatingVisitor}
+         * @param gvs The glyphs to draw. Sorted along the line
+         * @param isDoubleTranslationBug true to fix a double translation bug.
+         */
         GlyphRotatingVisitor(List<OffsetGlyph> gvs, boolean isDoubleTranslationBug) {
             this.isDoubleTranslationBug = isDoubleTranslationBug;