Some commenting
diff --git a/src/main/java/com/googlesource/gerrit/plugins/avatars/external/ExternalUrlAvatarProvider.java b/src/main/java/com/googlesource/gerrit/plugins/avatars/external/ExternalUrlAvatarProvider.java
index f19696c..6ac6dc3 100644
--- a/src/main/java/com/googlesource/gerrit/plugins/avatars/external/ExternalUrlAvatarProvider.java
+++ b/src/main/java/com/googlesource/gerrit/plugins/avatars/external/ExternalUrlAvatarProvider.java
@@ -62,16 +62,17 @@
       return null;
     }
 
+    // it is unrealistic that all users share the same avatar image, thus we're warning if we can't find our marker (%s)
     if (!externalAvatarUrl.contains(REPLACE_MARKER)) {
         Logger log = LoggerFactory.getLogger(ExternalUrlAvatarProvider.class);
         log.warn("Avatar provider url '" + externalAvatarUrl + "' does not contain " + REPLACE_MARKER + ", so cannot replace it with username");
         return null;
     }
 
+    // as the Gerrit only sends a 302 Found, the avatar is loaded by the user agent and thus SSL matters for the avatar image, if Gerrit uses SSL
     if (ssl && externalAvatarUrl.startsWith("http://")) {
     	externalAvatarUrl = externalAvatarUrl.replace("http://", "https://");
     }
-
     return replaceInUrl(externalAvatarUrl, forUser.getUserName());
   }
 
@@ -81,13 +82,19 @@
     return replaceInUrl(avatarChangeUrl, forUser.getUserName());
   }
 
-
+  /**
+   * Takes #{replacement} and substitutes the marker REPLACE_MARKER in #{url} after it has been URL encoded
+   * @param url The URL, usually containing #{REPLACE_MARKER}
+   * @param replacement String to be put inside
+   * @return new URL
+   */
   private String replaceInUrl(String url, String replacement) {
 
     if (replacement == null || url == null || url.contains(REPLACE_MARKER) == false) {
       return url;
     }
 
+    // as we can't assume anything of 'replacement', we're URL encoding it
     String encodedReplacement = null;
     try {
       encodedReplacement = URLEncoder.encode(replacement, "UTF-8");